swagger.yaml

swagger: '2.0'
info:
  version: 0.4.0
  title: 'Respa'
  description: 'Resource reservation system for City of Helsinki'
host: api.hel.fi
basePath: /respa/v1
tags:
  - name: resource
    description: Look for available resources
  - name: reservation
    description: Make or change your reservations
  - name: unit
    description: Places where resources are located
  - name: equipment
    description: Equipment available for use in the resources
  - name: filter
    description: Properties you can use in filtering resources
  - name: search
    description: Typeahead suggestions for objects
produces:
  - application/json
consumes:
  - application/json
paths:
  /search/:
    get:
      tags:
        - search
      description:
        Get typeahead suggestions for objects based on an arbitrary user input (the `input` query parameter).

        Currently supported are "resource" and "unit".
      parameters:
        - name: input
          in: query
          description: Query search parameter
          required: true
          type: string
        - name: full
          in: query
          description: Return all properties with the objects
          required: false
          type: boolean
        - name: types
          in: query
          description: Return only objects of the specified types
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              resource:
                type: array
                items:
                  $ref: '#/definitions/resource'
              unit:
                type: array
                items:
                  $ref: '#/definitions/unit'

  /unit/:
    get:
      tags:
        - unit
      description:
        The unit endpoint returns City of Helsinki units (libraries, youth centers etc.) listed in the reservation system.

        Returns 20 units per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 units per page.
      parameters:
        - name: resource_group
          in: query
          required: false
          type: string
          description: Only return units whose resources belong to the speficied resource group(s). Accepts multiple comma-separated values.
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of units per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/unit'
  /unit/{id}/:
    get:
      tags:
        - unit
      description:
        The unit endpoint returns City of Helsinki units (libraries, youth centers etc.) listed in the reservation system.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier for the City of Helsinki unit in the City of Helsinki service registry.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/unit'
  /purpose/:
    get:
      tags:
        - filter
      description: |
        The purpose endpoint returns the possible resource usage purposes registered in the system.

        Returns 50 purposes per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 50 purposes per page.
      parameters:
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of purposes per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/purpose'
  /purpose/{id}/:
    get:
      tags:
        - filter
      description:
        The purpose endpoint returns the possible resource usage purposes registered in the system.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier of the usage purpose.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/purpose'
  /type/:
    get:
      tags:
        - filter
      description: |
        The type endpoint returns the possible resource types registered in the system.

        Returns 20 types per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 units per page.
      parameters:
        - name: resource_group
          in: query
          required: false
          type: string
          description: Only return types for which there are resources that belong to the speficied resource group(s). Accepts multiple comma-separated values.
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of types per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/type'
  /type/{id}/:
    get:
      tags:
        - filter
      description:
        The type endpoint returns the possible resource types registered in the system.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier of the resource type.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/type'
  /equipment/:
    get:
      tags:
        - equipment
      description:
        The equipment endpoint returns the pieces of equipment of the resources.

        Returns 20 pieces of equipment per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 pieces of equipment per page.
      parameters:
        - name: resource_group
          in: query
          required: false
          type: string
          description: Only return pieces of equipment that belong to the speficied resource group(s). Accepts multiple comma-separated values.
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of pieces of equipment per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/equipment'
  /equipment/{id}/:
    get:
      tags:
        - equipment
      description:
        The equipment endpoint returns the pieces of equipment of the resources.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier for the piece of equipment.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/equipment'
  /equipmentcategory/:
    get:
      tags:
        - equipment
      description:
        The equipment category endpoint returns the possible categories for the pieces of equipment.

        Returns 20 equipment categories per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 equipment categories per page.
      parameters:
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of equipment categories per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/equipmentcategory'
  /equipmentcategory/{id}/:
    get:
      tags:
        - equipment
      description:
        The equipment category endpoint returns the possible categories for the pieces of equipment.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier for the City of Helsinki equipment category in the City of Helsinki service registry.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/equipmentcategory'
  /resource/:
    get:
      tags:
        - resource
      description: |
        The resource endpoint returns resources (meeting rooms, workstations, reservable spaces etc.) listed in the reservation system.

        The endpoint allows queries based on resource purpose, type, name and availability. Availability can be specified for a desired duration in a desired time interval. This allows fetching only the resources that match a particular need at a particular time.

        Returns 20 resources per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 units per page.
      parameters:
        - name: purpose
          in: query
          description: Only return resources that have the specified purpose(s)
          required: false
          type: string
        - name: type
          in: query
          description: Only return resources of the specified type(s). Accepts multiple comma-separated values.
          required: false
          type: string
        - name: search
          in: query
          description: Only return resources matching the specified string
          required: false
          type: string
        - name: start
          in: query
          description: Use together with `end`. Only return resources that are free within the specified interval.
          required: false
          type: string
          format: date-time
        - name: end
          in: query
          description: Use together with `start`. Only return resources that are free within the specified interval.
          required: false
          type: string
          format: date-time
        - name: duration
          in: query
          description: Use together with `start` and `end`. Only return resources that are free for a consecutive period of `duration` minutes within the specified interval.
          required: false
          type: number
        - name: during_closing
          in: query
          description: Use together with `start` and `end`. Include resources that are free but closed within the specified interval.
          required: false
          type: boolean
        - name: people
          in: query
          description: Only return resources with greater or equal capacity
          required: false
          type: number
        - name: equipment
          in: query
          required: false
          type: string
          description: Only return resources that contain the specified piece(s) of equipment. Accepts multiple comma-separated values.
        - name: resource_group
          in: query
          required: false
          type: string
          description: Only return resources that belong to the speficied resource group(s). Accepts multiple comma-separated values.
        - name: available_between
          in: query
          required: false
          type: string
          description: Only return resources that are open and free on the given datetime range. Expects two comma-separated datetimes as start and end time. Accepts also a third comma-separated value (period length in minutes), which can be used to determine a minimum free slot length that must exists in the main time range.
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of resources per page
          required: false
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/resource'
  /resource/{id}/:
    get:
      tags:
        - resource
      description:
        The resource endpoint returns resources (meeting rooms, workstations, reservable spaces etc.) listed in the reservation system.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier for the resource in the reservation system.
          required: true
        - name: start
          in: query
          description: Use together with `end`. Specifies starting time for reporting opening hours, availability and reservations.
          required: false
          type: string
          format: date-time
        - name: end
          in: query
          description: Use together with `start`. Specifies ending time for reporting opening hours, availability and reservations.
          type: string
          format: date-time
        - name: duration
          in: query
          description: Use together with `start` and `end`. Specifies minimum free period duration for resource availability.
          required: false
          type: number
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/resource'
  /reservation/:
    get:
      tags:
        - reservation
      description: |
        The reservation endpoint returns reservations listed in the reservation system.

        Returns 20 reservations per page. The optional parameter **page** allows specifying page number. **page_size** allows specifying more than 20 units per page.
      parameters:
        - name: page
          in: query
          description: Result page number
          required: false
          type: integer
        - name: page_size
          in: query
          description: Number of reservations per page
          required: false
          type: integer
        - name: resource
          in: query
          description: Resource id, for filtering reservations by resource
          required: false
          type: string
        - name: all
          in: query
          description: Display also past reservations. Default to false.
          required: false
          type: boolean
        - name: need_manual_confirmation
          in: query
          description: Filter reservations based on their need of a manual confirmation from unit personnel.
          required: false
          type: boolean
        - name: state
          in: query
          description: 'Display only reservation(s) in given state(s). Possible values: cancelled, confirmed, denied and requested.'
          required: false
          type: string
        - name: can_approve
          in: query
          description: Display reservations that the request user has the right to approve.
          required: false
          type: boolean
        - name: resource_group
          in: query
          required: false
          type: string
          description: Only return reservations for resources in the specified resource group(s). Accepts multiple comma-separated values.
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              count:
                type: integer
                description: 'The total number of results'
              next:
                type: string
                description: 'URL for the next page'
              prev:
                type: string
                description: 'URL for the previous page'
              results:
                type: array
                items:
                  $ref: '#/definitions/reservation'
    post:
      tags:
        - reservation
      description:
        The reservation endpoint accepts reservations.
      parameters:
        - name: reservation
          in: body
          description: The reservation you wish to make
          schema:
            $ref: '#/definitions/reservation'
          required: true
      responses:
        '201':
          description: Reservation created
          schema:
            $ref: '#/definitions/reservation'
        '400':
          description: Bad request
          schema:
            type: object
            properties:
              non_field_errors:
                type: string
                description: 'The reason the reservation was not accepted'

  /reservation/{id}/:
    get:
      tags:
        - reservation
      description:
        The reservation endpoint returns reservations listed in the reservation system.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier of the reservation in the reservation system.
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/reservation'
    put:
      tags:
        - reservation
      description:
        The reservation endpoint allows editing existing reservations.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier of the reservation in the reservation system.
          required: true
        - name: reservation
          in: body
          description: The reservation data you wish to edit
          schema:
            $ref: '#/definitions/reservation'
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/reservation'
        '400':
          description: Bad request
          schema:
            type: object
            properties:
              non_field_errors:
                type: string
                description: 'The reason the change was not accepted'
    delete:
      tags:
        - reservation
      description:
        The reservation endpoint allows deleting existing reservations.
      parameters:
        - name: id
          in: path
          type: string
          description: Unique identifier of the reservation in the reservation system.
          required: true
      responses:
        '204':
          description: Reservation deleted

definitions:
  unit:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier for the City of Helsinki unit in the City of Helsinki service registry.'
      opening_hours_today:
        type: object
        description: ''
      created_at:
        type: string
        description: ''
      modified_at:
        type: string
        description: ''
      name:
        type: object
        properties:
          sv:
            type: string
            description: 'Swedish name for the unit'
          fi:
            type: string
            description: 'Finnish name for the unit'
          en:
            type: string
            description: 'English name for the unit'
      description:
        type: string
        description: ''
      time_zone:
        type: string
        description: 'tz database name of the time zone used at the unit'
      street_address:
        type: object
        properties:
          sv:
            type: string
            description: 'Swedish address for the unit'
          fi:
            type: string
            description: 'Finnish address for the unit'
          en:
            type: string
            description: 'English address for the unit'
      address_zip:
        type: string
        description: 'Zip code for the street address'
      phone:
        type: string
        description: 'Phone number'
      email:
        type: string
        description: 'Contact email address'
      www_url:
        type: object
        properties:
          sv:
            type: string
            description: 'Swedish WWW URL for the unit'
          fi:
            type: string
            description: 'Finnish WWW URL for the unit'
          en:
            type: string
            description: 'English WWW URL for the unit'
      address_postal_full:
        type: string
        description: ''
      picture_url:
        type: string
        description: 'URL of unit picture'
      picture_caption:
        type: string
        description: ''
      created_by:
        type: string
        description: ''
      modified_by:
        type: string
        description: ''
      location:
        $ref: '#/definitions/location'

  location:
    type: object
    properties:
      type:
        type: string
        description: 'GeoJSON object geometry type'
      coordinates:
        type: array
        description: 'GeoJSON object coordinates'
        items:
          type: number

  purpose:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier of the usage purpose'
      parent:
        type: string
        description: 'The parent purpose of this purpose, or null, if this purpose is main purpose type'
      name:
        type: object
        properties:
          fi:
            type: string
            description: 'The purpose in Finnish'
          en:
            type: string
            description: 'The purpose in Finnish'

  type:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier of the resource type'
      main_type:
        type: string
        description: 'The main category of this resource type'
      name:
        type: object
        properties:
          fi:
            type: string
            description: 'Resource type in Finnish'

  reservation:
    type: object
    properties:
      url:
        type: string
        description: 'URL of the reservation'
      resource:
        type: string
        description: 'Unique identifier of the reserved resource'
      user:
        type: string
        description: 'Unique identifier of the user who made the reservation'
      begin:
        type: string
        description: 'The starting time of the reservation in ISO 8601 format'
      end:
        type: string
        description: 'The ending time of the reservation in ISO 8601 format'
      is_own:
        type: boolean
        description: 'Is the reservation is made by the current user.'
        readOnly: true
      state:
        type: string
        description: 'The state the reservation is currently in.'
        enum: ['cancelled', 'confirmed', 'denied', 'requested']
      need_manual_confirmation:
        type: boolean
        description: 'Does the reservation require a confirmation from the unit personnel?'
        readOnly: true
      reserver_name:
        type: string
        description: 'Reserver name'
      reserver_phone_number:
        type: string
        description: 'Reserver phone number'
      reserver_address_street:
        type: string
        description: 'Reserver street address'
      reserver_address_zip:
        type: string
        description: 'Reserver address zip code'
      reserver_address_city:
        type: string
        description: 'Reserver address city'
      billing_address_street:
        type: string
        description: 'Billing street address'
      billing_address_zip:
        type: string
        description: 'Billing address zip code'
      billing_address_city:
        type: string
        description: 'Billing address city'
      company:
        type: string
        description: 'Reserver company'
      event_description:
        type: string
        description: 'Description of the event the reservation is for'
      business_id:
        type: string
        description: 'Business ID of the reserver company'
      number_of_participants:
        type: integer
        description: 'Number of participants in the reservation'
      reserver_email_address:
        type: string
        description: 'Reserver email address'

  resource:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier of the resource in the reservation system'
      purposes:
        type: array
        description: 'Usage purposes for this resource'
        items:
          $ref: '#/definitions/purpose'
      type:
        $ref: '#/definitions/type'
      available_hours:
        type: array
        description: 'The intervals when the resource is not reserved during the queried period'
        items:
          type: object
      opening_hours:
        type: array
        description: 'The intervals when the resource is open during the queried period'
        items:
          type: object
      reservable:
        type: boolean
        description: 'Is it possible to create or modify reservations for this resource through the API. Even if this is false, reservations by other means (eg. phone call) might still be possible.'
      reservations:
        type: array
        description: 'The reservations made for the resource during the queried period'
        items:
          $ref: '#/definitions/reservation'
      created_at:
        type: string
      modified_at:
        type: string
      name:
        type: object
        properties: 
          fi: 
            type: string
            description: 'Resource name in Finnish'
      description:
        type: object
        properties: 
          fi: 
            type: string
            description: 'Resource description in Finnish'
      photo:
        type: string
        description: 'URL of resource picture'
      need_manual_confirmation:
        type: boolean
        description: 'Does making a reservation require confirmation from the unit personnel?'
      authentication:
        type: string
        description: 'The type of authentication required to reserve the resource'
      people_capacity:
        type: number
        description: 'The maximum number of people for the resource'
      area:
        type: number
        description: 'The floor area, in sq. m.'
      ground_plan:
        type: string
        description: 'URL of the floor plan'
      min_period:
        type: string
        description: 'The minimum duration of a reservation for the resource, in hh:mm:ss'
      max_period:
        type: string
        description: 'The maximum duration of a reservation for the resource, in hh:mm:ss'
      created_by:
        type: string
      modified_by:
        type: string
      unit:
        type: string
        description: 'Unique identifier for the City of Helsinki unit where the resource is located'
      location:
        $ref: '#/definitions/location'
      equipment:
        type: object
        description: 'The resource specific equipment instances'
        properties:
          id:
            type: string
            description: 'Unique identifier of the piece of equipment'
          name:
            type: object
            properties:
              fi:
                type: string
                description: 'Finnish name for the piece of equipment'
              en:
                type: string
                description: 'English name for the piece of equipment'
              sv:
                type: string
                description: 'Swedish name for the piece of equipment'
          description:
            type: string
            description: 'Description of the resource specific equipment instance'
          data:
            type: object
            additionalProperties:
              type: string
            description: 'Additional data related to the resource specific equipment instance'

  equipment:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier of the piece of equipment'
      category:
        type: object
        description: 'The equipment category the piece of equipment belongs to'
        properties:
          id:
            type: string
            description: 'Unique identifier of the equipment category'
          name:
            type: object
            properties:
              fi:
                type: string
                description: 'Finnish name for the equipment category'
              en:
                type: string
                description: 'English name for the equipment category'
              sv:
                type: string
                description: 'Swedish name for the equipment category'
      name:
        type: object
        properties:
          fi:
            type: string
            description: 'Finnish name for the piece of equipment'
          en:
            type: string
            description: 'English name for the piece of equipment'
          sv:
            type: string
            description: 'Swedish name for the piece of equipment'
      aliases:
        type: array
        description: 'Aliases for the piece of equipment'
        items:
          type: object
          properties:
            name:
              type: string
              description: 'The name of the equipment alias'
            language:
              type: string
              description: 'The language of the equipment alias. "fi", "sv" or "en".'

  equipmentcategory:
    type: object
    properties:
      id:
        type: string
        description: 'Unique identifier of the equipment category'
      name:
        type: object
        properties:
          fi:
            type: string
            description: 'Finnish name for the equipment category'
          en:
            type: string
            description: 'English name for the equipment category'
          sv:
            type: string
            description: 'Swedish name for the equipment category'
      equipment:
        type: array
        description: 'The pieces of equipment that belong to the equipment category'
        items:
          type: object
          properties:
            id:
              type: string
              description: 'Unique identifier of the piece of equipment'
            name:
              type: object
              properties:
               fi:
                 type: string
                 description: 'Finnish name for the piece of equipment'
               en:
                 type: string
                 description: 'English name for the piece of equipment'
               sv:
                 type: string
                 description: 'Swedish name for the piece of equipment'