APDS_API.yaml

openapi: 3.0.0
info:
  title: APDS
  version: '1.0'
  description: |-
    Allows the standard CRUD operations, as well as listing/search of:

    * `Places` (and their `Occupancy`)
    * `Rates`
    * `RightSpecifications`
    * `AssignedRights`
    * `Sessions`
    * `Observations`

    **IMPORTANT**: This specification is a working **DRAFT**. Please **do not use it as the basis for APDS implementations at this stage**.
  contact: {}
tags:
  - name: create
    description: Create a resource
  - name: read
    description: Read a resource
  - name: update
    description: Update a resource
  - name: delete
    description: Delete a resource
  - name: list
    description: Search and list resources
  - name: example
    description: An example endpoint that data consumers should implement
servers:
  - url: ''
paths:
  /rights/assigned:
    parameters: []
    post:
      summary: Create a new AssignedRight
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                created:
                  value:
                    status: ok
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
      operationId: create-assigned_right
      description: Create a new `AssignedRight` based on a given object or referencing a `Quote`
      requestBody:
        description: This method allows an issuer to assign a parking right to a holder
        content:
          application/json:
            schema:
              oneOf:
                - $ref: ../models/right/AssignedRight.yaml
                - $ref: ../models/right/ReferenceToQuote.yaml
      tags:
        - create
    get:
      summary: List and Search for AssignedRights
      operationId: list-assigned_rights
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    description: 'the actual data'
                    properties:
                      data:
                        type: array
                        description: Result set with `AssignedRights` and requested expanded attributes
                        items:
                          $ref: ../models/right/AssignedRight.yaml
      description: |-
        Lists `AssignedRights` and allows searching/filtering by:

        * one or more `HolderCredentials` and `RightSpecifications`, to check if given credentials have any of the given rights to park
        * latitude, longitude, radius: to check for `AssignedRights` within a geographic area
        * a list of `Places`, to retrieve all assigned rights within a set of parking locations
        * start_before: to get sessions starting before a given instant
        * end_before: to get sessions ending before a given instant
        * start_after: to get sessions starting after a given instant
        * end_after: to get sessions ending after a given instant
        * a modification instant: to only display changed resources from that point onwards

        Additionally, supports providing a comma-separated list of optional object attributes associated to an `AssignedRight` that should be included in the result set. If unused or left blank, `none` will be assumed.
      tags:
        - list
      parameters:
        - $ref: '#/components/parameters/right_specs_list'
        - $ref: '#/components/parameters/cred_type'
        - $ref: '#/components/parameters/cred_class_list'
        - $ref: '#/components/parameters/cred_id_list'
        - $ref: '#/components/parameters/place_list'
        - $ref: '#/components/parameters/assigned_expand'
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/start_before'
        - $ref: '#/components/parameters/end_before'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/end_after'
  '/rights/assigned/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        description: Identifier for the `AssignedRight`
        required: true
    delete:
      summary: Delete AssignedRight
      operationId: delete-assigned_right
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                bad-request:
                  value:
                    status: error
                    code: 400
                    message: Did not provide version number
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      tags:
        - delete
      description: Delete an existing `Assigned Right`
    put:
      summary: Update AssignedRight
      operationId: update-assigned_right
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      description: 'Update an existing `AssignedRight` based on its object or with reference to a `Quote`. If the Quote refers to a Session Extension, this request shall also update the referenced Session'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: ../models/right/AssignedRight.yaml
                - $ref: ../models/right/ReferenceToQuote.yaml
        description: 'The new version of the `AssignedRight`, including only its changed attributes'
      tags:
        - update
    get:
      summary: Get an AssignedRight
      operationId: read-assigned_right
      description: Get latest version of a given `AssignedRight` by its identifier (or a particular previous version when provided as a query parameter)
      tags:
        - read
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/assigned_expand'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/right/AssignedRight.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
  /rights/specs:
    get:
      summary: List and search for RightSpecifications
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        description: Result set with `RightSpecifications` and requested expanded attributes
                        items:
                          $ref: ../models/right/RightSpecification.yaml
      operationId: list-rights-specs
      description: |-
        Lists `RightSpecifications` and allows filtering by:

        * latitude, longitude, radius: to check for `RightSpecifications` within a geographic area
        * a `Place`, to retrieve all assigned rights within a parking location
        * a modification instant: to only display changed resources from that point onwards

        Additionally, supports providing a comma-separated list of optional object attributes associated to an `RightSpecification` that should be included in the result set. If unused or left blank, `none` will be assumed.
      parameters:
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/specs_expand'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/cred_type'
        - $ref: '#/components/parameters/place_list'
    post:
      summary: Create a new RightSpecification
      operationId: post-rights-specs
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      tags:
        - create
      description: Create a new `RightSpecification`
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/right/RightSpecification.yaml
        description: The new RightSpec
  '/rights/specs/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Identifier for the `RightSpecification`
    get:
      summary: Get a RightSpecification
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/right/RightSpecification.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      operationId: get-rights-specs-id
      description: Get latest version of a given `RightSpecification` by its identifier (or a particular previous version when provided as a query parameter)
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/specs_expand'
    put:
      summary: Update a RightSpecification
      operationId: put-rights-specs-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/right/RightSpecification.yaml
        description: 'The new version of the `RightSpecification`, including only its changed attributes'
      description: Update an existing `RightSpecification`
      tags:
        - update
    delete:
      summary: Delete RightSpecification
      operationId: delete-rights-specs-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                bad-request:
                  value:
                    status: error
                    code: 400
                    message: Did not provide version number
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      tags:
        - delete
      description: Delete a `RightSpecification`
  /rates:
    get:
      summary: List and Search for RateTables
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ../models/rate/RateTable.yaml
      operationId: get-rates
      description: |-
        Lists `RateTables` and allows searching/filtering by:

        * latitude, longitude, radius: to check for `AssignedRights` within a geographic area
        * a list of `Places`, to retrieve all rates connected to `AssignedRights` that belong to any of the given places
        * a list of `RightSpecifications`, to retrieve all the connected 
        * a modification instant: to only display changed resources from that point onwards

        Additionally, supports providing a comma-separated list of optional object attributes associated to a `RateTable` that should be included in the result set. If unused or left blank, `none` will be assumed.
      parameters:
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/rates_expand'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/place_list'
        - $ref: '#/components/parameters/right_specs_list'
    post:
      summary: Create a new RateTable
      operationId: post-rates
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Create a `RateTable`
      tags:
        - create
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/rate/RateTable.yaml
        description: The new RateTable
  '/rates/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Identifier for the `RateTable`
    get:
      summary: Get a RateTable
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/rate/RateTable.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      operationId: get-rates-id
      description: Get latest version of a given `RateTable` by its identifier
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/rates_expand'
    put:
      summary: Update a RateTable
      operationId: put-rates-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      tags:
        - update
      description: Update an existing `RateTable`
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/rate/RateTable.yaml
        description: 'The new version of the `RateTable`, including only its changed attributes'
    delete:
      summary: Delete RateTable
      operationId: delete-rates-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                bad-request:
                  value:
                    status: error
                    code: 400
                    message: Did not provide version number
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      tags:
        - delete
      description: Delete an existing `RateTable`
  '/places/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for place hierarchy element
    get:
      summary: Read an element in the Place hierarchy
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/HierarchyElementData.yaml
      operationId: get-places-id
      description: Get latest version of a given place hierarchy element by its identifier (or a particular previous version when provided as a query parameter)
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/places_expand'
    put:
      summary: Update Place hierarchy element
      operationId: put-places-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Update an element in the `Place` hierarchy (or one of its associated attributes like `Occupancy`)
      tags:
        - update
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/api/HierarchyElementData.yaml
        description: 'The new version of the `Place` hierarchy element, including only its changed attributes. In the case of Occupancy updates, the Place version does not need to change.'
    delete:
      summary: Delete Place hierarchy element
      operationId: delete-places-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Delete Place hierarchy element
      tags:
        - delete
  /places:
    get:
      summary: List and search for elements in the Place hierarchy
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        description: Hierarchy elements matching filters
                        items:
                          $ref: ../models/api/HierarchyElementData.yaml
                    description: Data response
      operationId: get-places
      description: |-
        Lists `Places` and allows searching/filtering by:

        * `latitude`, `longitude`, `radius`: to check for elements in the `Place` hierarchy within a geographic area
        * a modification instant (`modified_since`): to only display changed resources from that point onwards
        * `layer`: maximum hierarchy element layer desired
        * `type`: types of hierarchy elements
        * `right_type`: types of `RightSpecifications` associated with Place hierarchy elements
        * `structure_type`: types of structure
        * `structure_grade`: grades of structures
        * `name`: name of facilities

        Additionally, supports providing a comma-separated list of optional object attributes associated to a `Place` hierarchy element that should be included in the result set. (see `expand` attribute). If unused or left blank, `none` will be assumed.
      parameters:
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/places_expand'
        - schema:
            type: integer
          in: query
          name: layer
          description: 'Most detailed (lower-level) layer of data desired. 0 (zero) being the first level (and higher numbers correspond to lower-levels of information). If left empty, the entire Place hierarchy that matches the remaining parameters will be returned'
        - $ref: '#/components/parameters/place_type'
        - $ref: '#/components/parameters/right_type'
        - $ref: '#/components/parameters/structure_type'
        - $ref: '#/components/parameters/structure_grade'
        - schema:
            type: string
          in: query
          name: name
          description: Name of place hierarchy element (in any of its supported languages)
        - $ref: '#/components/parameters/mod'
    post:
      summary: Create a new Place hierarchy element
      operationId: post-places
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      tags:
        - create
      description: Create a new element in the `Place` hierarchy
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/api/HierarchyElementData.yaml
        description: The new Place
  /sessions:
    get:
      summary: List and Search for Sessions
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ../models/session/Session.yaml
      operationId: get-sessions
      description: |-
        Lists `Sessions` and allows searching/filtering by a combination of:

        * latitude, longitude, radius: to check for `Sessions` ocurring in a geographic area (via the associated Place hierarchy element)
        * a list of `Places`, to retrieve all sessions connected to the given elements in the place hierarchy
        * a list of `RightSpecifications`, to retrieve all sessions with segments using any of the given rights
        * one or more `HolderCredentials` to get sessions linked to the given credentials
        * startBefore: to get sessions starting before a given instant
        * endBefore: to get sessions ending before a given instant
        * startAfter: to get sessions starting after a given instant
        * endAfter: to get sessions ending after a given instant
        * a modification instant: to only display changed resources from that point onwards

        Additionally, supports providing a comma-separated list of optional object attributes associated to a `Session` or `Segment` that should be included in the result set. If unused or left blank, `none` will be assumed.
      parameters:
        - $ref: '#/components/parameters/right_specs_list'
        - $ref: '#/components/parameters/cred_type'
        - $ref: '#/components/parameters/cred_class_list'
        - $ref: '#/components/parameters/cred_id_list'
        - $ref: '#/components/parameters/place_list'
        - $ref: '#/components/parameters/sessions_expand'
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/start_before'
        - $ref: '#/components/parameters/end_before'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/end_after'
    post:
      summary: Create a new Session
      operationId: post-sessions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: 'Allows the creation of a new Session, along with one or more Segments. It also allows the creation of an AssignedRight, for scenarios in which the Session and the AssignedRight are created simultaneously (e.g. off-street and on-street short stays)'
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/session/Session.yaml
        description: 'The Session, Segments (and potentially AssignedRight) to create'
      tags:
        - create
  '/sessions/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Identifier for the `Session`
    get:
      summary: Get a Session
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/session/Session.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      operationId: get-sessions-id
      description: Get latest version of a given `Session` by its identifier (or a particular previous version when provided as a query parameter)
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/sessions_expand'
    put:
      summary: Update an existing Session
      operationId: put-sessions-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      description: 'Update an existing Session (or Segment). Segments may also be deleted using this method, by removing them from the list of segments under the Session. Session may also be updated by referencing a `Quote` through a `ReferenceQuoteExtension`'
      tags:
        - update
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: ../models/session/Session.yaml
                - $ref: ../models/right/ReferenceQuoteExtension.yaml
        description: 'The `Session` (and `Segments`) to update, including only their changed attributes'
    delete:
      summary: Delete a Session
      operationId: delete-sessions-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      tags:
        - delete
      description: 'Delete an existing `Session`. `Segments` should be deleted by using the `PUT` operation, and removing them from the list of segments under the session'
  /observations:
    get:
      summary: List and search Observations
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: ../models/observation/ObservationElement.yaml
      operationId: get-observations
      description: |-
        Lists `Observations` and allows searching/filtering by:

        * latitude, longitude, radius: to check for `Observations` within a geographic area
        * a list of `Places`, to retrieve all Observations within a set of parking locations
        * start_before: to get observations starting before a given instant
        * end_before: to get observations ending before a given instant
        * start_after: to get observations starting after a given instant
        * end_after: to get observations ending after a given instant
        * a modification instant: to only display changed resources from that point onwards

        Additionally, supports providing a comma-separated list of optional object attributes associated to an `Observation` that should be included in the result set. If unused or left blank, `none` will be assumed.
      parameters:
        - $ref: '#/components/parameters/place_list'
        - $ref: '#/components/parameters/observations_expand'
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/start_before'
        - $ref: '#/components/parameters/end_before'
        - $ref: '#/components/parameters/start_after'
        - $ref: '#/components/parameters/end_after'
    post:
      summary: Create an Observation or Observation Set
      operationId: post-observations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Create a singular `Observation` or an `Observation Set`
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: ../models/observation/ObservationElement.yaml
                - $ref: ../models/observation/ObservationSet.yaml
        description: The ObservationElement or ObservationSet to create
      tags:
        - create
  '/observations/{id}':
    get:
      summary: Get an Observation
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/observation/ObservationElement.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      operationId: get-observations-id
      description: Get latest version of a given `Observation` by its identifier (or a particular previous version when provided as a query parameter)
      parameters:
        - $ref: '#/components/parameters/version'
        - $ref: '#/components/parameters/observations_expand'
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for `Observation`
    put:
      summary: Update an existing Observation
      operationId: put-observations-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      description: Update an existing `Observation`
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/observation/ObservationElement.yaml
        description: 'The new version of the `Observation`, including only its changed attributes'
      tags:
        - update
    delete:
      summary: Delete an `Observation`
      operationId: delete-observations-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                missing-data:
                  value:
                    status: error
                    code: 400
                    message: Missing required attributes
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                not-found:
                  value:
                    status: error
                    code: 404
                    message: Not found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
              examples:
                conflict:
                  value:
                    status: error
                    code: 409
                    message: Outdated version number provided
      description: Delete an existing `Observation`
      tags:
        - delete
  /webhooks:
    post:
      summary: Subscribe to event topics
      operationId: post-webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the event subscription
                    required:
                      - id
                  - $ref: ../models/api/ResponseStatus.yaml
      description: Allows an entity with an accessible API endpoint to subscribe to a set of event topics
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/api/EventSubscription.yaml
        description: The event subscription configuration
      callbacks:
        placeEvent:
          '{$request.body#/endpoint}':
            post:
              summary: The endpoint for webhook subscribers
              responses:
                '200':
                  description: OK
              description: |-
                This endpoint describes the payloads that webhook subscribers should expect to receive

                **IMPORTANT**: This specification is a working **DRAFT**. Please **do not use it as the basis for APDS implementations at this stage**.
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: ../models/api/EventData.yaml
                description: The event payload
      tags:
        - create
  '/webhooks/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: The unique identifier for the event subscription
    get:
      summary: Get an event subscription
      tags:
        - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the event
                      lastModified:
                        type: string
                        description: Last modified timestamp
                        format: date-time
                    required:
                      - id
                      - lastModified
                  - $ref: ../models/api/EventSubscription.yaml
      operationId: get-webhooks-id
      description: Get current configuration for an event subscription
    put:
      summary: Update an event subscription
      operationId: put-webhooks-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Update an existing event subscription to a different set of settings
      requestBody:
        content:
          application/json:
            schema:
              $ref: ../models/api/EventSubscription.yaml
        description: The new settings for the event subscription
      tags:
        - update
    delete:
      summary: Delete an event subscription
      operationId: delete-webhooks-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: ../models/api/ResponseStatus.yaml
      description: Delete an event subscription
      tags:
        - delete
  /quotes:
    get:
      summary: List QuoteRequests or QuoteResponses
      tags:
        - list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          anyOf:
                            - $ref: ../models/quote/QuoteRightResponse.yaml
                            - $ref: ../models/quote/QuoteSessionExtensionResponse.yaml
                            - $ref: ../models/quote/QuoteRightRequest.yaml
                            - $ref: ../models/quote/QuoteSessionExtensionRequest.yaml
      operationId: get-quotes
      description: Lists recorded quote requests and/or responses
      parameters:
        - $ref: '#/components/parameters/lat'
        - $ref: '#/components/parameters/long'
        - $ref: '#/components/parameters/radius'
        - $ref: '#/components/parameters/quotes_expand'
        - $ref: '#/components/parameters/mod'
        - $ref: '#/components/parameters/place_list'
        - $ref: '#/components/parameters/right_specs_list'
        - $ref: '#/components/parameters/quote_type'
    post:
      summary: Create a Quote Request
      operationId: post-quotes
      tags:
        - create
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ../models/api/PaginatedListMeta.yaml
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          oneOf:
                            - $ref: ../models/quote/QuoteSessionExtensionResponse.yaml
                            - $ref: ../models/quote/QuoteRightResponse.yaml
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: ../models/quote/QuoteRightRequest.yaml
                - $ref: ../models/quote/QuoteSessionExtensionRequest.yaml
      description: Creates a Quote Request for any eligible RightSpecifications (via `QuoteRightRequest`) or to extend an existing session (via `QuoteSessionExtensionRequest`)
  '/quotes/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: the unique id of the quote
    get:
      summary: Your GET endpoint
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                anyOf:
                  - {}
                type: object
      operationId: get-quotes-id
      description: Retrieves a specific QuoteRequest or QuoteResponse. The `type` element is mandatory
      parameters:
        - $ref: '#/components/parameters/quotes_expand'
        - $ref: '#/components/parameters/quote_filter'
components:
  schemas: {}
  parameters:
    lat:
      schema:
        type: number
        format: float
      in: query
      name: latitude
      description: Location latitude to use as filter (mandatory if longitude or radius are defined)
    long:
      schema:
        type: number
        format: float
      in: query
      name: longitude
      description: Location longitude to use as filter (mandatory if longitude or radius are defined)
    radius:
      schema:
        type: integer
        minimum: 0
      in: query
      name: radius
      description: Number of metres to use as search filter from given latitude and longitude (mandatory if latitude or longitude are defined)
    mod:
      schema:
        type: integer
        minimum: 0
      in: query
      name: modified_since
      description: |-
        Reference timestamp to only display resources that have changed after that instant (represented as seconds, in UTC, since epoch).

        * If `expand` attributes are requested, then this timestamp will also applyto those objects’ modifications 
        * When this attribute is used, the result-set will also include a list of deleted resources’ IDs, so that the client can use this method to avoid storing stale data
    assigned_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - plannedUses
            - assignedRightIssuer
      description: Comma-separated list of optional object attributes associated to an `AssignedRight` that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    version:
      schema:
        type: integer
        minimum: 1
      in: query
      name: version
      description: 'Previous version number. Useful when a reference to a resource version is found in another dataset, and that version is no longer the latest one. Latest version is assumed when this parameter is not used.'
    specs_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - rateEligibility
            - validity
            - credentials
            - rightPools
      description: Comma-separated list of optional object attributes associated to an `RightSpecification` that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    cred_type:
      schema:
        type: array
        items:
          $ref: ../models/enums/CredentialTypeEnum.yaml
      name: credential_type
      in: query
      description: Type of credential
      style: form
      explode: false
    places_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - rightSpecifications
            - occupancy
            - areaLocation
            - pointLocation
            - contacts
            - operatingRestrictions
            - characteristics
            - paymentMethods
            - openingTimes
            - streetAddress
      description: Comma-separated list of optional object attributes associated to a `Place` hierarchy element that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    right_type:
      schema:
        type: array
        items:
          $ref: ../models/enums/RightTypeEnum.yaml
      name: right_type
      in: query
      description: Comma-separated list of type of `RightSpecifications` associated with place hierarchy elements (all will be assumed if parameter is not used or left blank)
      style: form
      explode: false
    place_type:
      schema:
        type: array
        items:
          $ref: ../models/enums/HierarchyElementTypeEnum.yaml
      name: type
      in: query
      description: Comma-separated list of type of `Place` hierarchy elements to consider (all will be assumed if parameter is not used or left blank)
      style: form
      explode: false
    structure_type:
      schema:
        type: array
        items:
          $ref: ../models/enums/StructureTypeEnum.yaml
      name: structure_type
      in: query
      description: Comma-separated list of types of Structure in the hierarchy to consider (all will be assumed if parameter is not used or left blank)
      style: form
      explode: false
    structure_grade:
      schema:
        type: array
        items:
          $ref: ../models/enums/StructureGradeEnum.yaml
      name: structure_grade
      in: query
      description: Comma-separated list of Structure grades in the hierarchy to consider (all will be assumed if parameter is not used or left blank)
      style: form
      explode: false
    rates_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - rateLineCollections
            - rateLineCollections.rateLines
      style: form
      explode: false
      description: Comma-separated list of optional object attributes associated to a `RateTable` that should be included in the result set
      name: expand
      in: query
    place_list:
      schema:
        type: array
        items:
          type: string
      description: Comma-separated list of unique identifiers for elements in the `Place` hierarchy
      name: place
      in: query
      explode: false
      style: form
    right_specs_list:
      schema:
        type: array
        items:
          type: string
      description: Comma-separated list of unique identifiers for `RightSpecifications`
      name: right_spec
      in: query
      explode: false
      style: form
    cred_id_list:
      schema:
        type: array
        items:
          type: string
      in: query
      name: credential_id
      description: Comma-separated list of unique identifiers for credentials in given classes
      style: form
      explode: false
    cred_class_list:
      schema:
        type: array
        items:
          type: string
      in: query
      name: credential_class
      description: Comma-separated list of specific class names for credentials (a more generic option is to use `credential_type`)
      style: form
      explode: false
    end_after:
      schema:
        type: integer
        minimum: 0
      in: query
      name: end_after
      description: 'Unix epoch instant in UTC, to filter results ending after the given instant'
    start_after:
      schema:
        type: integer
        minimum: 0
      in: query
      name: start_after
      description: 'Unix epoch instant in UTC, to filter results starting after the given instant'
    end_before:
      schema:
        type: integer
        minimum: 0
      in: query
      name: end_before
      description: 'Unix epoch instant in UTC, to filter results ending before the given instant'
    start_before:
      schema:
        type: integer
        minimum: 0
      in: query
      name: start_before
      description: 'Unix epoch instant in UTC, to filter results starting before the given instant'
    sessions_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - credentials
            - segments
            - segments.financialTransactions
            - segments.space
            - segments.assignedRight
            - vehicleAncilliaryIdentification
      description: Comma-separated list of optional object attributes associated to an `Session` (or `Segment`) that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    observations_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - images
            - hierarchyElement
            - vehicleAncilliaryIdentification
      description: Comma-separated list of optional object attributes associated to an `Observation` that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    quotes_expand:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - none
            - options
      description: Comma-separated list of optional object attributes associated to a `QuoteRequest` or `QuoteResponse` that should be included in the result set
      name: expand
      in: query
      style: form
      explode: false
    quote_type:
      schema:
        type: array
        items:
          type: string
          enum:
            - all
            - QuoteRightRequest
            - QuoteRightResponse
            - QuoteSessionExtensionRequest
            - QuoteSessionExtensionResponse
      name: type
      in: query
      description: Comma-separated list of type of `Quote` type elements to consider (all will be assumed if parameter is not used or left blank)
      style: form
      explode: false
    quote_filter:
      schema:
        type: string
        enum:
          - QuoteRightRequest
          - QuoteRightResponse
          - QuoteSessionExtensionRequest
          - QuoteSessionExtensionResponse
      name: type
      in: query
      description: Type of `Quote` type element to consider
      style: form
      explode: false