openapi: 3.0.3
info:
  title: Service Desk Card Reader API
  version: 0.9.0
  description: |-
    This API enables that external systems (such as SOS) can operate on information from service desk card readers.

    ### 0.9.0
    - First draft version
servers:
  - url: /v1
paths:
  /card-reader/token:
    post:
      tags:
        - CardReader
      summary: Register a token from the card
      operationId: registerToken
      description: |
        Register a token from the card to the external system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRegisterRequest"
      responses:
        "202":
          description: Accepted
        "400":
          description: |-
            Bad Request. Occurs when the readerId is unknown to the external system. A call to `/card-reader/registrations`, 
            followed by a `/card-reader/register` is needed in order to restore reader registrations.
  /card-reader/register:
    post:
      tags:
        - CardReader
      summary: Register a reader that is connected to the Card Reader Interface
      operationId: registerReader
      description: |
        Register a reader to the external system to receive a newly generated readerID.

        **N.B.**: After the last reader has been registered, an initial `/card-reader/registrations` call must be sent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReaderRegisterRequest"
      responses:
        "200":
          description: Registration was successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReaderRegisterResponse"
        "400":
          description: Bad Request

  /card-reader/unregister:
    post:
      tags:
        - CardReader
      summary: Unregister a reader from the external system
      operationId: unregisterReader
      description: |
        Unregister a reader from the external system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReaderUnregisterRequest"
      responses:
        "204":
          description: Unregistration was successful
        "400":
          description: Bad Request
  /card-reader/registrations:
    post:
      tags:
        - CardReader
      summary: Send a list of readers that should currently be registered
      operationId: sendReaderRegistrations
      description: |
        Send a list of readers of which the Card Reader Interface believes are registered. This must be done periodically.
        The period is determined by the timeout duration in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegistrationsRequest"
      responses:
        "200":
          description: Reader registrations successfully received
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistrationsResponse"

components:
  schemas:
    TokenRegisterRequest:
      description: Request containing token information read using the card reader
      type: object
      properties:
        readerId:
          $ref: "#/components/schemas/ReaderId"
        xBot:
          type: string
          format: uuid
          description: The unique identifier of the token.
      required:
        - readerId
        - xBot

    ReaderRegisterRequest:
      description: Request containing card reader information for one or more readers to be be registered
      type: object
      properties:
        readerIdQuantity:
          type: integer
          default: 1
          minimum: 1
        cardReaderInterfaceId:
          $ref: "#/components/schemas/cardReaderInterfaceId"
        locationName:
          $ref: "#/components/schemas/LocationName"
      required:
        - cardReaderInterfaceId
        - locationName
        - readerIdQuantity
    ReaderRegisterResponse:
      description: Response containing one or more readerIds for the registered reader(s)
      type: object
      properties:
        readerIds:
          type: array
          items:
            $ref: "#/components/schemas/ReaderId"
      required:
        - readerIds

    ReaderUnregisterRequest:
      description: Request containing the readerId to unregister
      type: object
      properties:
        cardReaderInterfaceId:
          $ref: "#/components/schemas/cardReaderInterfaceId"
        locationName:
          $ref: "#/components/schemas/LocationName"
        readerId:
          $ref: "#/components/schemas/ReaderId"
      required:
        - readerId

    RegistrationsRequest:
      description: Request containing a list of readerId of which the Card Reader Interface believes are registered.
      type: object
      properties:
        cardReaderInterfaceId:
          $ref: "#/components/schemas/cardReaderInterfaceId"
        locationName:
          $ref: "#/components/schemas/LocationName"
        readerIds:
          type: array
          items:
            $ref: "#/components/schemas/ReaderId"
      required:
        - cardReaderInterfaceId
        - locationName
        - readerIds
    RegistrationsResponse:
      description: Response with actionable information for the Card Reader Interface.
      type: object
      properties:
        nextCallTimeout:

          type: integer
          description: |
            Timeout duration in seconds BEFORE which the next `/card-reader/registrations` call should happen. 
            Failure to send a call before this timeout will result in automatic unregistration of all readers associated to this Card Read Interface.

            The external systems must maintain a grace period on reception of the next call.
            The Card Read Interface must start sending the next call on or before the timeout (grace period not needed).
        readerIds:
          type: array
          items:
            $ref: "#/components/schemas/ReaderId"
          description: |
            A list of readerIds that are registered to the external system. This mean all readerIds that readers with 
            readerIds missing from this list must be reregistered using `/card-reader/register`.
      required:
        - nextCallTimeout
        - readerIds

    cardReaderInterfaceId:
      type: string
      description: Each Card Reader Interface has a unique cardReaderInterfaceId. Identifier for the Card Reader Interface to which one or more readers are connected.
    LocationName:
      type: string
      description: Name of the location of the reader. A location can have one ore more Card Reader Interfaces (cardReaderInterfaceIds)
    ReaderId:
      type: string
      description: Unique identifier generated by the external system. Should be displayed on the screen of the reader.