src/openapi/nfc_reader/servicedeskcardreader-api.yaml

@@ -0,0 +1,206 @@
+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.