lsis-openapi.yaml

# ------------------------------------------------------------------------------
# SPDX-FileCopyrightText: 'Copyright Contributors to the LSIS project'
#
# SPDX-License-Identifier: Apache-2.0
# ------------------------------------------------------------------------------

openapi: 3.0.3
info:
  title: LSIS API (REST)
  version: 0.0.12
  description: |
    This API enables on-demand querying of station occupancy through RESTful services.

    **Version 0.0.9**
    - Initiate version numbering from the final Events-proposal-lsis-v8.jsonc, adhering to semantic versioning principles.
    - The first version to be implemented by all grid operators will be designated as 1.0.0.
    - Add descriptions from Events-proposal-lsis-v8.jsonc to API endpoints.
    - Add which properties are required and which objects allow additional properties.
    - Add missing attendees object definition.

    **Version 0.0.10**
    - Introduced cursor-based pagination to the /api/stations/v1/occupancy endpoint to efficiently handle large datasets, 
      allowing clients to use cursor and limit parameters to navigate through paginated results.

    **Version 0.0.11**
    - Add bad request to path responses.
    - Add descriptions to responses in order to better clarify their purpose.
    - The `occupied` parameter is now a boolean.
    - remove `anyOf` construct for error responses since not all frameworks support this.
    - types of error response properties are made more explicit.
    - Change urls to be compliant with NBility model.
    - Change securitySchemes to oAuth2. (The tokenUrl and refreshUrl are unknown at this moment).

    **Version 0.0.12**
    - Add missing `occupiedSince` property to `ElectricityStationOccupancyResponse`
    - The `attendees` array should now be populated when the station is occupied and when retrieving 
      the occupancies of all stations via the `/occupancy` endpoint.
  contact:
    name: LSIS Support
    email: support@landelijksis.net
  license:
    name: MIT
    url: https://opensource.org/license/mit
  x-releaseDate: 10/31/2024

servers:
  - url: https://api.landelijksis.net/energy-grid/grid-function/station-occupancy-retrieval/v1/
    description: LSIS production server

security:
  - oAuth2: []

paths:
  /occupancy/{id}:
    get:
      summary: Retrieve occupancy of an electricity station with `id`.
      description: |
        REST/JSON API-endpoint for occupancy of a specific station with the given `id`.
        If 'guestOf' is not set, the attendee is keyholder. 
        If set, the value indicates an attending keyholder to which the guest is bound.
      operationId: retrieveElectricityStationOccupancy
      parameters:
        - "$ref": "#/components/parameters/StationIdParam"
        - "$ref": "#/components/parameters/AuthHeaderParam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElectricityStationOccupancyResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

  /occupancy:
    get:
      summary: Retrieve occupancy of all electricity stations
      description: |
        REST/JSON API-endpoint for global attendance on all caller visible stations.
      operationId: getAllStationsOccupancy
      parameters:
        - name: occupied
          in: query
          required: false
          schema:
            type: boolean
          description: Whether to return only occupied stations
        - "$ref": "#/components/parameters/CursorParam"
        - "$ref": "#/components/parameters/LimitParam"
        - "$ref": "#/components/parameters/AuthHeaderParam"
      responses:
        "200":
          description: Occupancy details for the requested stations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElectricityStationsOccupancyResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"

components:
  securitySchemes:
    oAuth2:
      type: oauth2
      description: This API uses OAuth 2 with the client credentials flow.
      flows:
        clientCredentials:
          tokenUrl: todo
          refreshUrl: todo
          scopes: {}
  schemas:
    StationIdParam:
      type: string
    AuthHeaderParam:
      type: string
    BadRequest:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 400
        title:
          type: string
          enum:
            - Bad Request
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1
        detail:
          type: string
        instance:
          type: string
          format: uri
    Unauthorized:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 401
        title:
          type: string
          enum:
            - Unauthorized
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7235#section-3.1
        detail:
          type: string
        instance:
          type: string
          format: uri
    Forbidden:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 403
        title:
          type: string
          enum:
            - Forbidden
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3
        detail:
          type: string
        instance:
          type: string
          format: uri
    NotFound:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 404
        title:
          type: string
          enum:
            - Not Found
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
        detail:
          type: string
        instance:
          type: string
          format: uri
    InternalServerError:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 500
        title:
          type: string
          enum:
            - Internal Server Error
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1
        detail:
          type: string
        instance:
          type: string
          format: uri
    ServiceUnavailable:
      type: object
      required: [status, title, type]
      properties:
        status:
          type: number
          format: int32
          enum:
            - 503
        title:
          type: string
          enum:
            - Service Unavailable
        type:
          type: string
          format: uri
          enum:
            - https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.4
        detail:
          type: string
        instance:
          type: string
          format: uri
    ElectricityStationOccupancyResponse:
      type: object
      properties:
        data:
          type: object
          required: [id, occupied, externalIds, attendees]
          additionalProperties: false
          properties:
            id:
              type: string
              description: Station ID
            occupied:
              type: boolean
              description: Whether the station is occupied
            occupiedSince:
              type: string
              format: date-time
              description: Date and time the station became occupied.
                <p><b>Note:</b> This value is only required when the `occupied` is true.</p>
            externalIds:
              type: array
              items:
                type: object
                required: [sysop, refId]
                properties:
                  sysop:
                    type: string
                    description: Tenant identifier of the grid operator
                  refId:
                    type: string
                    description: Reference identifier of the station at the grid operator
            attendees:
              type: array
              items:
                type: object
                required:
                  [userId, fullName, isContactPerson, attendingSince, company]
                additionalProperties: false
                properties:
                  userId:
                    type: string
                    format: uuid
                    description: Key management identifier of the attendee
                  fullName:
                    type: string
                    description: Full name of the attendee
                  phoneNumber:
                    type: string
                    description: <p>Phone number of the attendee.</p>
                      <p>Phone numbers are provided by EntraID for key holders, and by Certwell for guests</p>
                      <p><b>Note:</b> This value is required when the attendee is a contact person or key holder.</p>
                  isContactPerson:
                    type: boolean
                    description: Indicates whether the attendee is the contact person at the station.
                  guestOf:
                    type: string
                    format: uuid
                    description:
                      Key management identifier of the attendee this attendee is the guest of.

                      <p><b>Note:</b> This value is only required when the attendee is a guest.</p>
                  registeredBy:
                    type: string
                    format: uuid
                    description:
                      Key management identifier of the person that registered the attendee.

                      <p><b>Note:</b> This value is only required when the attendee is registered by someone else.</p>
                  attendingSince:
                    type: string
                    format: date-time
                    description: Date and time the attendee arrived at the station.
                  company:
                    type: string
                    description: Company of the attendee
      example:
        data:
          id: KX023s1
          occupied: true
          occupiedSince: "2024-04-04T10:31:00Z"
          externalIds:
            - sysop: A123-4563-4B13
              refId: "000000002"
          attendees:
            - userId: GUID-2733
              fullName: Conny ter Plaatse
              phoneNumber: "31677777777"
              isContactPerson: true
              guestOf: GUID-bab3
              registeredBy: GUID-caf3
              attendingSince: "2024-04-04T10:31:00Z"
              company: Stedin

    ElectricityStationsOccupancyResponse:
      type: object
      required: [data, responseMetadata]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ElectricityStationOccupancyResponse"
        responseMetadata:
          type: object
          properties:
            nextCursor:
              type: string
              description: |
                A token included in the response that indicates the position of the next set of results. 
                Clients should use this token in the cursor parameter of the next request to continue 
                retrieving paginated results.
      example:
        data:
          - id: KX023s1
            occupied: true
            occupiedSince: "2024-04-04T10:31:00Z"
            externalIds:
              - sysop: A123-4563-4B13
                refId: "000000002"
            attendees:
              - userId: GUID-2733
                fullName: Conny ter Plaatse
                phoneNumber: "31677777777"
                isContactPerson: true
                guestOf: GUID-bab3
                registeredBy: GUID-caf3
                attendingSince: "2024-04-04T10:31:00Z"
                company: Stedin
        responseMetadata:
          nextCursor: "dXNlcjpVMEc5V0ZYTlo="

  parameters:
    StationIdParam:
      schema:
        "$ref": "#/components/schemas/StationIdParam"
      required: true
      description: ID of the station to retrieve
      name: id
      in: path
    AuthHeaderParam:
      schema:
        "$ref": "#/components/schemas/AuthHeaderParam"
      required: true
      description: Bearer token for authentication
      name: Authorization
      in: header
    CursorParam:
      schema:
        type: string
      required: false
      description: |
        A token used to retrieve the next set of results. This token is provided in the nextCursor field 
        of the previous response. It represents the position of the last item in the current page of results 
        and is used to fetch the subsequent page.
      name: cursor
      in: query
      example: "dXNlcjpVMEc5V0ZYTlo="
    LimitParam:
      schema:
        type: integer
        minimum: 1
        maximum: 100
      required: false
      description: |
        The maximum number of items to return in the response. 
        This parameter controls the size of the page and helps manage the volume of data returned in each request.
      name: limit
      in: query
      example: 20

  responses:
    BadRequest:
      description: >
        Bad Request. The server could not understand the request due to invalid syntax. 
        The client should not repeat this request without modification.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/BadRequest"
    Unauthorized:
      description: >
        Unauthorized. The request requires valid user authentication. 
        The client must authenticate itself to get the requested response. 
        This status is sent when the request lacks valid authentication credentials.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/Unauthorized"
    Forbidden:
      description: >
        Forbidden. The server understood the request but refuses to authorize it. 
        The client does not have access rights to the content; that is, it is unauthorized, 
        so the server is refusing to give the requested resource. 
        Unlike a 401 Unauthorized response, authenticating will make no difference.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/Forbidden"
    NotFound:
      description: >
        Not Found. The server can not find the requested resource. 
        This status code is typically used when the server does not want to reveal exactly 
        why the request has been refused, or when no other response is applicable.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/NotFound"
    InternalServerError:
      description: >
        Internal Server Error. The server has encountered a situation it doesn't know how to handle. 
        This status code is a generic error message, given when no more specific message is suitable.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/InternalServerError"
    ServiceUnavailable:
      description: >
        Service Unavailable. The server is not ready to handle the request. 
        Common causes are a server that is down for maintenance or that is overloaded. 
        This status code implies that the server will be available at a later time.
      content:
        application/problem+json:
          schema:
            "$ref": "#/components/schemas/ServiceUnavailable"