[api] Added first draft of the population statistics API.

README.md

@@ -1,4 +1,4 @@
-API docs written in OpenAPI (swagger/redocly) format.
+# API docs written in OpenAPI (swagger/redocly) format
 
 * API docs can be rendered into stand-alone HTML with: `npm start`.
 * API text can be linted with `npm test`

paths/population_statistics.yaml

@@ -0,0 +1,78 @@
+get:
+  tags:
+    - population
+  operationId: "populationStatistics"
+  summary: "Get a population count divided by items like age, preferred doctor, etc."
+  description: |-
+    A table with at least two columns. The first column is a category of age, preferred doctor, etc. The second, the number of patients in the category. The category can be extended by several more group by items.
+
+    Patients who are no longer registrered are excluded, so only patients with an active registration are included. Patients without birthdate are excluded (rare).
+  parameters:
+    - name: referenceDate
+      in: query
+      required: true
+      schema: 
+        type: "string"
+        pattern: "\\d\\d\\d\\d-\\d\\d-\\d\\d"
+        format: "date"
+        description: ISO formatted date
+        example: 2015-12-15
+    - name: groupByItems
+      in: query
+      required: true
+      style: form
+      explode: false
+      schema:
+        type: string
+        enum:
+        - age
+        - preferredDoctor
+        - insurer
+        - gender
+        - deprivedNeighborhood
+        description: "Several items can be added to the group by using a comma separated list, e.g. `groupByItems=gender,age`. If an item is twice or more repeated the first occurance is used. Only known ages are outputted. The insurer is outputted as an Uzovi (with name and concern). The most recent Uzovi table is used to convert codes to names and concerns. The sequence of the items in the URL is the same as the sequence in the grouping of the output."
+    - name: insurer
+      in: query
+      style: form
+      explode: false
+      schema: 
+        $ref: ../schemas/insurer-Uzovi.yaml
+      description: "Supply zero, one or more Uzovi's to limit the responses to certain insurer. Use 0 to select all patients without insurer registred. Supply the Uzovi code as an integer in a comma separated list, e.g. `insurer=101,211,3344`."
+    - name: passerBy
+      in: query
+      schema: 
+        type: boolean
+        description: "True to include passer-by patients. This also includes Medicom's noni patients. (Noni = niet op naam ingeschreven.) By default passer-by patients are excluded from the response."
+    - $ref: '../zoo-api.yaml#/components/parameters/Authorization'
+  responses:
+    200:
+      description: "The response body is a JSON-array with for each group, defined by a sequence of `groupByItem` query parameters, an object with a count `n`."
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                age:
+                  type: number
+                  example: 42
+                preferredDoctor:
+                  $ref: '../schemas/PatIdentity.yaml#/doctor'
+                insurer:
+                  $ref: '../schemas/PatIdentity.yaml#/insurer'
+                gender:
+                  $ref: '../schemas/PatIdentity.yaml#/gender'
+                n:
+                  type: number
+                  description: "The number of unique patients in the group."
+                  example: 7
+    400:
+      description: "Common HTTP semantics, see the response body."
+    401:
+      $ref: '../zoo-api.yaml#/components/responses/JwtFailure'
+    403:
+      description: "Indicated practice is known but has not authorized ZOO to share this information with signer."
+    404:
+      $ref: '../zoo-api.yaml#/components/responses/PatNotFound'
+

schemas/PatIdentity.yaml

@@ -111,13 +111,20 @@ insurance:
       type: string
       example: 123456789012345
     uzovi:
-      description: |-
-        Insurer's identity number in the dutch insurance system (dutch: _UZOVI nummer_).
-        
-        A value between 0 (no insurance) and 9999; these numbers are customary rendered as 4 digits.
-        When rendering, we suggest callers left-pad with zeroes.
-      type: number
-      example: 101
+      $ref: 'insurer-Uzovi.yaml'
+insurer:
+  type: object
+  properties:
+    uzovi:
+      $ref: 'insurer-Uzovi.yaml'
+    name:
+      type: string
+      description: "The name of the insurer according the [Vektis register](https://www.vektis.nl/uzovi-register). If the Uzovi is unknown, the Uzovi code is used as the name. The latest register is used to lookup the name for the code."
+      example: "FBTO Zorgverzekeringen N.V."
+    concern:
+      type: string
+      description: "The concern name, if any, otherwise the empty string."
+      example: "ACHMEA"
 patid:
   $ref: 'pat-patId.yaml'
 pat_unid:

schemas/insurer-Uzovi.yaml

@@ -0,0 +1,6 @@
+description: |-
+  Insurer's identity number in the dutch insurance system (dutch: _UZOVI nummer_).
+  
+  A value between 0 (no insurance) and 9999; these numbers are customary rendered as 4 digits. When rendering, we suggest callers to left-pad with zeroes.
+type: number
+example: 0211

zoo-api.yaml

@@ -14,6 +14,8 @@ info:
 #    description: Production
 #  - url: https://test.zorgoporde.nl/api1
 #    description: Testing
+security: 
+  -  
 tags:
   - name: core
     description: |-
@@ -22,6 +24,9 @@ tags:
     description: |-
       API for retrieving medical dossier data and concerns based on looking up a
       specific patient.
+  - name: population
+    description: |-
+      Population statistics.
   - name: Quality of Care
     description: |-
       API related to Quality of Care (QoC) features
@@ -36,14 +41,14 @@ 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:
     $ref: 'paths/springboard_apps.yaml'
-
   /patient/dossier:
     $ref: 'paths/patient_dossier.yaml'
   /patient/base:
     $ref: 'paths/patient_base.yaml'
+  /population/statistics:
+    $ref: 'paths/population_statistics.yaml'
   /qoc/careprogram:
     $ref: 'paths/qoc_careprogram.yaml'
   /qoc/careprogram/{careprogramKey}/fave:
@@ -137,4 +142,3 @@ components:
                 enum:
                   - practice
                   - patient
-