[api] Added careprogram object. Added description for /customer/careprogram/enddate end point.

paths/customer_careprogram.yaml

@@ -2,7 +2,7 @@ get:
   operationId: getCustomerCareProgram
   tags:
     - Customer management
-  summary: All practices and their participation in care programs.
+  summary: Get all practices and their participation in any care program.
   description: |-
     Enumerates all practices for which the current customer (user) is responsible in the care group. The customer identified with the JWT must be the group manager, otherwise the API will respond with a HTTP not authorized response. The care group must also be responsible for the underlying practices. Some care groups are organized in a way that they are not allowed to process data of the member practices. These groups are ignored by this API and produce empty output.
   parameters: 
@@ -26,10 +26,17 @@ get:
                 careprograms:
                   type: array
                   items:
-                    $ref: '../schemas/CareProgram-enum.yaml'
+                    type: object
-                  example: 
+                    properties:
-                    - DM
+                      careprogram:
-                    - COPD
+                        $ref: '../schemas/CareProgram-enum.yaml'
+                      periodStart:
+                        $ref: ../schemas/date.yaml
+                      periodEnd:
+                        $ref: ../schemas/date.yaml
+                      active:
+                        type: boolean
+                        description: True if today is on or after `periodStart` and before `periodEnd`.
                 gpis:
                   $ref: '../schemas/GPIS.yaml'
     '401':
@@ -40,7 +47,7 @@ post:
   tags: 
     - Customer management
   operationId: setCustomerCareProgram
-  summary: Adds a practice to a care program.
+  summary: Add a practice to a care program.
   description: |-
     Allows a care group manager to classify practices into care groups (ziektebeelden, ketens). 
     
@@ -79,14 +86,16 @@ post:
   responses:
     '200':
       description: |-
-        If and only if, the request was successful processed down to the database, a Json-object with the following properties is send back to the caller, otherwise an empty Json-object. 
+        If and only if, the request was successful processed down to the database, a Json-object with the following properties is send back to the caller, otherwise a non 200 HTTP response.
-        
-        The API is idempotent for the combination of `careprogram`, `agb`, `periodStart`, `periodEnd`. If an attempt is made to store such a combination again, then the response is like a successful response, but the employee and timestamp are of the previous request.
       content:
         'application/json':
           schema:
             type: object
             properties:
+              employee:
+                type: string
+              timestamp:
+                $ref: ../schemas/dateTime.yaml
               careprogram:
                 $ref: '../schemas/CareProgram-enum.yaml'
               agb:
@@ -95,10 +104,6 @@ post:
                 $ref: ../schemas/date.yaml
               periodEnd:
                 $ref: ../schemas/date.yaml
-              employee:
-                type: string
-              timestamp:
-                $ref: ../schemas/dateTime.yaml
     '401':
       $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
     '403':

paths/customer_careprogram_periodEnd.yaml

@@ -0,0 +1,55 @@
+post:
+  tags: 
+    - Customer management
+  operationId: setCustomerCareProgramPeriodEnd
+  summary: Update the period end of a practice in a care program.
+  description: |-
+    This API allows to update only the period end date of the participation of a practice in a care program. This is equivalent to submitting a new participation to this API, but only the `periodStart` parameter is not needed.
+  requestBody: 
+    content: 
+      'application/x-www-form-urlencoded':
+        schema:
+          type: object
+          properties:
+            careprogram:
+              description: The kind of care program that the practice participates in. 
+              $ref: '../schemas/CareProgram-enum.yaml'
+            agb:
+              description: The AGB of the practice (not the doctor).
+              $ref: '../schemas/agb.yaml'
+            employee:
+                type: string
+                description: The employee that is adding the practice. Any string is accepted, but it is recommended to use a employee code derived from this API.
+            periodEnd:
+              description: The end of the period of the participation. Allowed to be not set or empty, when no end date is known. If set, `periodEnd` must be at least a day after the `periodStart` which is stored for the combination of `careprogram` and `agb`.
+              $ref: ../schemas/date.yaml
+          required: 
+              - careprogram
+              - agb
+              - employee
+  responses:
+    '200':
+      description: |-
+        If the request was successful processed a Json-object with the following properties is send back to the caller, otherwise a non 200 HTTP response. 
+      content:
+        'application/json':
+          schema:
+            type: object
+            properties:
+              employee:
+                type: string
+              timestamp:
+                $ref: ../schemas/dateTime.yaml
+              careprogram:
+                $ref: '../schemas/CareProgram-enum.yaml'
+              agb:
+                $ref: '../schemas/agb.yaml'
+              periodStart:
+                $ref: ../schemas/date.yaml
+              periodEnd:
+                $ref: ../schemas/date.yaml
+    '401':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAuth'
+    '403':
+      $ref: '../zoo-api.yaml/#/components/responses/NoAccess'
+      

schemas/date.yaml

@@ -1,4 +1,7 @@
-description: Date without time part in ISO-8601 format. Dates are processed using Java's java.util.GregorianCalender in non-lenient mode. That for example means that 2023-02-29, which was not in a leap year, is intepreted as 2023-03-01.
+description: |-
+  Date without time part in ISO-8601 format. 
+  
+  Note on submitting dates to this API. Dates are processed using Java's java.util.GregorianCalender in non-lenient mode. That for example means that 2023-02-29, which was not in a leap year, is intepreted as 2023-03-01.
 type: string
 format: date
 example: "1970-01-13"

zoo-api.yaml

@@ -81,6 +81,8 @@ paths:
     $ref: 'paths/qoc_participating-practices.yaml'
   /customer/careprogram:
     $ref: 'paths/customer_careprogram.yaml'
+  /customer/careprogram/periodEnd:
+    $ref: 'paths/customer_careprogram_periodEnd.yaml'
 components:
   parameters:
     Authorization: