swagger: '2.0'
info:
  version: 2.0.1
  title: Bike and Ride API
  description: >-
    This API can be used to receive information about Bike and Ride sites and their availability.

schemes:
  - https
paths:
  /site:
    get:
      tags:
        - Bike and Ride API
      description: Find all available Bike and Ride sites
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/SiteSummary'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '403':
          description: Forbidden.

  '/site/{id}/availability':
    get:
      tags:
        - Bike and Ride API
      description: Get availability information of the bike and ride slots for the given site id within the specified timeframe. Returns only the single most recent information if the query parameters "from" and "to" are not specified.
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: integer
          required: true
          description: The id of the Bike and Ride site to return the availability of.
        - in: query
          name: from
          type: string
          required: false
          description: Optional "From" filter - Timestamp (ISO 8601), i.e. 2019-03-31T16:45+00:00
        - in: query
          name: to
          type: string
          required: false
          description: Optional "To" filter - Timestamp (ISO 8601), i.e. 2019-03-31T16:45+00:00
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/Availability'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
          
  '/site/all/availability':
    get:
      tags:
        - Bike and Ride API
      description: Get availability information of the bike and ride slots for all sites within the specified timeframe. Returns only the single most recent information if the query parameters "from" and "to" are not specified.
      security:
        - ApiKey: []
      produces:
        - application/json
      parameters:
        - in: query
          name: from
          type: string
          required: false
          description: Optional "From" filter - Timestamp (ISO 8601), i.e. 2019-03-31T16:45+00:00
        - in: query
          name: to
          type: string
          required: false
          description: Optional "To" filter - Timestamp (ISO 8601), i.e. 2019-03-31T16:45+00:00
      responses:
        '200':
          description: ok
          schema:
            type: array
            items:
              $ref: '#/definitions/Site'
        '400':
          description: Bad Request.
        '401':
          description: Authorization required.
        '403':
          description: Forbidden.

securityDefinitions:
  ApiKey:
    type: apiKey
    name: x-api-key
    in: header
    
definitions:

  Stop:
    title: Stop
    type: object
    properties:
      ifopt:
        type: string
        description: The global ID of the stop
      name:
        type: string
        description: The name of the stop
      place:
        type: string
        description: The place of the stop

  SiteSummary:
    title: SiteSummary
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: integer
        description: The unique id of the B+R site.
      name:
        type: string
        description: The name of the B+R site.
      provider:
        type: string
        description: The operator of this B+R site.
      latitude:
        type: number
        description: The latitude of this B+R site.
      longitude:
        type: number
        description: The longitude of this B+R site.
      stop:
        $ref: '#/definitions/Stop'

  Site:
    title: Site
    allOf: 
      - $ref: '#/definitions/SiteSummary'
      - type: object
      - properties:
          availability:
            type: array
            items:
              $ref: '#/definitions/Availability'

  Availability:
    title: Availability
    type: object
    required:
      - timestamp
    properties:
      timestamp:
        type: string
        description: Timestamp of last change (ISO 8601), i.e. 2019-03-31T16:45+00:00
      inactive:
        type: integer
      defect:
        type: integer
      bookable:
        type: integer
      blocked:
        type: integer
      occupied:
        type: integer
      sum_boxes:
        type: integer