From a6312677d8d2fcb2bd814919aa5c5aa37ad03ce1 Mon Sep 17 00:00:00 2001
From: Reinier Zwitserloot <reinier@zwitserloot.com>
Date: Tue, 4 Apr 2023 20:35:15 +0200
Subject: [PATCH] [apidoc] Fleshed out Authorization for patient info endpoint

---
 api/ui_api.swagger.yaml | 91 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 6 deletions(-)

diff --git a/api/ui_api.swagger.yaml b/api/ui_api.swagger.yaml
index 4b77aed..86105e2 100644
--- a/api/ui_api.swagger.yaml
+++ b/api/ui_api.swagger.yaml
@@ -24,8 +24,7 @@ servers:
 tags:
   - name: core
     description: |-
-      API for cross-cutting API concerns, such as authentication.
-      TBD.
+      API for cross-cutting API concerns, such as authentication and the springboard.
   - name: patient
     description: |-
       API for retrieving medical dossier data and concerns based on looking up a
@@ -44,11 +43,44 @@ tags:
 
       As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report (essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default.
 paths:
+
+
+  /springboard/apps:
+    get:
+      tags:
+        - core
+      summary: Available springboard apps
+      responses:
+        '200':
+          description: List of available apps
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  notifications:
+                    type: string
+                  apps:
+                    type: array
+                    items:
+                      type: string
+          
   /patient/base:
     get:
       tags:
         - patient
       summary: Get basic personal info not directly related to their medical dossier
+      parameters:
+        - name: bsn
+          in: query
+          description: |-
+            The SSN (dutch: _BSN_) of a patient to look up. May only contain digits, cannot contain more than 9 digits, and cannot be 0.
+          required: true
+          schema:
+            type: string
+            example: 123456789
+        - $ref: '#/components/parameters/Authorization'
+
       responses:
         '200':
           description: Basic personal information for the patient is returned.
@@ -169,13 +201,16 @@ paths:
                           4 digits exactly, 0-left-padded if needed. If unknown or not insured, 4 zeroes.
                         type: string
                         example: 3331
+        '400':
+          description: The request is invalid; for example, it doesn't contain the required `BSN` parameter.
         '401':
-          $ref: '#/components/responses/NoAuth'
+          $ref: '#/components/responses/JwtFailure'
         '403':
-          $ref: '#/components/responses/NoAccess'
+          description: Indicated practice is known but has not authorized ZOO to share this information with signer.
         '404':
           $ref: '#/components/responses/PatNotFound'
   
+  
   /qoc/careprogram:
     get:
       tags:
@@ -448,14 +483,58 @@ components:
                 type: string
                 example: ZEL-dm2
 
-
+  
+  parameters:
+    Authorization:
+      name: Authorization
+      in: header
+      description: |-
+        Single-use signed JWT token with the following mandatory claims:
+        <ul>
+        <li><code>kid</code> – <strong>key id</strong>: A string identifying a trusted signer; agreed upon between user and Zorg op Orde beforehand.</li>
+        <li><code>iat</code> – <strong>Issued at</strong>: Time when this JWT was created and signed. Must be no more than 1 hour ago.
+        <li><code>jti</code> – <strong>JWT ID</strong>: A unique string used to prevent replay: Any given ID can not be used more than once.
+        <li><code>agb</code> – <strong>GP AGB</strong>: AGB code (Medical entity identifier); the lookup will be done on the medical dossier data of this practice or entity.
+        <li><code>exp</code> – <em>OPTIONAL</em> <strong>Expires at</strong>: If included, the request must not be received after this time.
+        <li><code>nbf</code> – <em>OPTIONAL</em> <strong>Not before</strong>: If included, the request must not be received before this time.
+        </ul>
+        The JWT must be signed, preferably with `HS256`.
+      required: true
+      schema:
+        type: string
+        example: >-
+          eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJraWQiOiJaT08tQVBJLVBLSS1JRCIsImFnYiI6IjAxMDEyMzQ1IiwiaWF0IjoxNTE2MjM5MDIyLCJqdGkiOiJ0MTIzNC01Njc4LUFCQ0QifQ.wTesCfFTq1Mz8z7hUWU6zzKSc3dopWnpeETR7eDzFtc
+  
   responses:
+    JwtFailure:
+      description: The JWT token isn't valid or wasn't provided.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              err:
+                description: A plain text explanation of what's wrong with the JWT token.
+                type: string
+                enum:
+                  - no JWT included
+                  - Unknown signer
+                  - Request sent before nfb
+                  - Request sent after exp
+                  - JWT issued too long ago
+                  - Signature missing
+                  - Signature invalid
+                  - Required claim missing (agb)
+                  - Required claim missing (iat)
+                  - Required claim missing (kid)
+                  - Required claim missing (jti)
+                  - JWT already used
     NoAuth:
       description: User is not logged in / session expired.
     NoAccess:
       description: User is not allowed to access this API endpoint.
     PatNotFound:
-      description: Provided filter does not match any patients or no medical dossiers are available for this patient.
+      description: Provided filter does not match any patients or no medical dossiers are available for this practice.
       content:
         application/json:
           schema: