From 5b7cbeeec7fa9914ffa4ed550160c6ce81aa8e6e Mon Sep 17 00:00:00 2001 From: Eric Hoekstra Date: Wed, 19 Jun 2024 16:41:42 +0200 Subject: [PATCH] Docs for customer care program POST added. --- paths/customer-careprogram.yaml | 30 --------- paths/customer_careprogram.yaml | 105 ++++++++++++++++++++++++++++++++ schemas/GPIS.yaml | 1 + schemas/agb.yaml | 4 ++ schemas/dateTime.yaml | 4 ++ zoo-api.yaml | 10 +-- 6 files changed, 117 insertions(+), 37 deletions(-) delete mode 100644 paths/customer-careprogram.yaml create mode 100644 paths/customer_careprogram.yaml create mode 100644 schemas/agb.yaml create mode 100644 schemas/dateTime.yaml diff --git a/paths/customer-careprogram.yaml b/paths/customer-careprogram.yaml deleted file mode 100644 index 0a739e3..0000000 --- a/paths/customer-careprogram.yaml +++ /dev/null @@ -1,30 +0,0 @@ -get: - operationId: customercareProgram - tags: - - Customer management - summary: All practices and their participation in care programs. - 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. - responses: - '200': - description: All practices for which the care group takes responsibility. - content: - application/json: - schema: - type: array - items: - type: object - properties: - practice: - description: The name of the practice. - type: string - careprograms: - type: array - items: - $ref: '../schemas/CareProgram-enum.yaml' - gpis: - $ref: '../schemas/GPIS.yaml' - '401': - $ref: '../zoo-api.yaml/#/components/responses/NoAuth' - '403': - $ref: '../zoo-api.yaml/#/components/responses/NoAccess' diff --git a/paths/customer_careprogram.yaml b/paths/customer_careprogram.yaml new file mode 100644 index 0000000..9162125 --- /dev/null +++ b/paths/customer_careprogram.yaml @@ -0,0 +1,105 @@ +get: + operationId: getCustomerCareProgram + tags: + - Customer management + summary: All practices and their participation in care programs. + 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: + - name: refDate + in: query + $ref: ../schemas/date.yaml + description: If omitted, today is taken. + responses: + '200': + description: All practices for which the care group takes responsibility. + content: + application/json: + schema: + type: array + items: + type: object + properties: + practice: + description: The name of the practice. + type: string + careprograms: + type: array + items: + $ref: '../schemas/CareProgram-enum.yaml' + example: + - DM + - COPD + gpis: + $ref: '../schemas/GPIS.yaml' + '401': + $ref: '../zoo-api.yaml/#/components/responses/NoAuth' + '403': + $ref: '../zoo-api.yaml/#/components/responses/NoAccess' +post: + tags: + - Customer management + operationId: setCustomerCareProgram + summary: Adds a practice to a care program. + description: |- + Allows a care group manager to classify practices into care groups (ziektebeelden, ketens). + + The caller must authorize itself as a care group (manager). If this requirement is not met, a 403 response is send back. + + The care group must be allowed to take responsibility for the practices it holds. If not, the request is ignored and an empty Json-object is send back to the caller. Indicating that processing was not successful. The practice must be one of the care group practices. If not, the request is ignored and an empty Json-object is send back to the caller. In all other cases a Json-object containing the same data as in the request with a timestamp added is send back in the response. + + The operation is idem potent for the combination of: `careprogram`, `agb`, `periodStart` and `periodEnd`. If these are the same in any subsequent call the request is processes as being fully accepted, showing the request data in the response, but the `employee` and `timestamp` aren't updated in the database. The timestamp of the original request is added to the response. + 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' + periodStart: + description: |- + For the API the period start and end are just properties. Only the constraint that periodStart < periodEnd is enforced. + $ref: ../schemas/date.yaml + periodEnd: + $ref: ../schemas/date.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. + required: + - careprogram + - agb + - periodStart + - employee + 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. + + 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: + careprogram: + $ref: '../schemas/CareProgram-enum.yaml' + agb: + $ref: '../schemas/agb.yaml' + periodStart: + $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': + $ref: '../zoo-api.yaml/#/components/responses/NoAccess' + \ No newline at end of file diff --git a/schemas/GPIS.yaml b/schemas/GPIS.yaml index e0c9c1d..877abb3 100644 --- a/schemas/GPIS.yaml +++ b/schemas/GPIS.yaml @@ -4,6 +4,7 @@ properties: gpisType: description: The type of GP Information System type: string + example: Tetrapod timestamp: description: |- The report is based on dossier data as it was on this timestamp; due to inaccuracies by GP information systems that source the data, diff --git a/schemas/agb.yaml b/schemas/agb.yaml new file mode 100644 index 0000000..2c168cb --- /dev/null +++ b/schemas/agb.yaml @@ -0,0 +1,4 @@ +type: integer +minimum: 1 +maximum: 99999999 +example: 1053293 \ No newline at end of file diff --git a/schemas/dateTime.yaml b/schemas/dateTime.yaml new file mode 100644 index 0000000..937552b --- /dev/null +++ b/schemas/dateTime.yaml @@ -0,0 +1,4 @@ +description: Date with time part in ISO-8601 format. +type: string +format: datetime +example: "1970-01-13T13:59:00.123456" diff --git a/zoo-api.yaml b/zoo-api.yaml index 84e5c20..23a3d43 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -80,7 +80,7 @@ paths: /qoc/participating-practices: $ref: 'paths/qoc_participating-practices.yaml' /customer/careprogram: - $ref: 'paths/customer-careprogram.yaml' + $ref: 'paths/customer_careprogram.yaml' components: parameters: Authorization: @@ -110,9 +110,7 @@ components: The JWT token must be authorized for this entity. required: false schema: - type: integer - minimum: 1 - maximum: 99999999 + $ref: '../schemas/agb.yaml' AgbCareGroup: name: agb in: query @@ -122,9 +120,7 @@ components: authenticating JWT token, it must be a query parameter. The JWT token must be authorized for this entity. required: false schema: - type: integer - minimum: 1 - maximum: 99999999 + $ref: '../schemas/agb.yaml' Pretty: name: pretty in: query