From 0e0ef924b8069c38e0c74aea2fd108ac86f9a226 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Thu, 8 Feb 2024 17:23:16 +0100 Subject: [PATCH 01/10] docs: add notification-api-v1 spec --- docs/api-specs/reporting-api-v1.yaml | 271 +++++++++++++++++++++++++-- 1 file changed, 260 insertions(+), 11 deletions(-) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index e72b67e..d1c8af0 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -2,8 +2,8 @@ openapi: 3.0.3 info: title: Aam Digital - Reporting API description: |- - API to manage reports that provide data calculated based on any entities of the Aam Digital system. - version: 1.0.0-alpha.1 + API to manage reports that provide data calculated based on any entities of the Aam Digital system and notifications. + version: 1.0.0-alpha.2 servers: - url: https://{customerId}.aam-digital.net/api/v1/reporting description: Developer Instance for testing @@ -13,13 +13,14 @@ servers: description: Customer ID assigned by the service provider tags: - name: report + - name: notification paths: /report: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Return list of available Reports @@ -34,12 +35,16 @@ paths: $ref: '#/components/schemas/Report' 401: description: If no valid access token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' /report/{reportId}: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Return report metadata by ID @@ -58,14 +63,22 @@ paths: $ref: '#/components/schemas/Report' 404: description: If the Report does not exist + content: + application/json: + schema: + $ref: '#/components/schemas/Error' 401: description: If the access token does not grant permission to this Report + content: + application/json: + schema: + $ref: '#/components/schemas/Error' /report-calculation/report/{reportId}: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Return all report calculations for a report @@ -84,13 +97,21 @@ paths: $ref: '#/components/schemas/ReportCalculation' 401: description: If the access token does not grant permission to this Report + content: + application/json: + schema: + $ref: '#/components/schemas/Error' 404: description: If report does not exist + content: + application/json: + schema: + $ref: '#/components/schemas/Error' post: security: - development: - - reports_write + - reporting_write tags: - report summary: Trigger a new report calculation run. @@ -127,12 +148,16 @@ paths: format: uuid 401: description: If the access token does not grant permission to this Report + content: + application/json: + schema: + $ref: '#/components/schemas/Error' /report-calculation/{calculationId}: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Return metadata for a report calculation @@ -153,14 +178,22 @@ paths: $ref: '#/components/schemas/ReportCalculation' 401: description: If the access token does not grant permission to this Report + content: + application/json: + schema: + $ref: '#/components/schemas/Error' 404: description: If the calculation identifier does not exist + content: + application/json: + schema: + $ref: '#/components/schemas/Error' /report-calculation/{calculationId}/data: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Fetch actual report data for a specific calculation @@ -172,7 +205,7 @@ paths: required: true responses: 200: - description: The actual data that has been calculated by the calculation run. This matches the schema defined in the /report/id + description: The actual data that has been calculated by the calculation run. This matches the schema defined in the /report/id content: application/json: schema: @@ -182,11 +215,167 @@ paths: $ref: '#/components/schemas/ReportData' 404: description: report data is not available yet (when either the calculation id is not valid or the calculation is still running) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' 401: description: If the access token does not grant permission to this Report + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + # notification + + /webhook: + get: + security: + - development: + - reporting_read + tags: + - notification + summary: Return list of existing Webhooks + responses: + 200: + description: List of all available Webhooks the requester has created, empty array if no Webhooks are available + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Webhook' + 401: + description: If no valid access token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: + description: No permissions to access the resource + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /webhook/{webhookId}: + get: + security: + - development: + - reporting_read + tags: + - notification + summary: Return a specific Webhook + parameters: + - in: path + name: webhookId + schema: + type: string + required: true + responses: + 200: + description: Get details of a webhook, including details of subscribed events and configuration + content: + application/json: + schema: + $ref: '#/components/schemas/Webhook' + 401: + description: If no valid access token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: + description: No permissions to access the resource + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 404: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /webhook/{webhookId}/subscribe/report/{reportId}: + post: + security: + - development: + - reporting_write + tags: + - notification + summary: Subscribe to events for a specific Report + parameters: + - in: path + name: webhookId + schema: + type: string + required: true + - in: path + name: reportId + schema: + type: string + required: true + responses: + 200: + description: Report added to webhook subscription + 401: + description: If no valid access token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: + description: No permissions to access the resource + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 404: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + delete: + security: + - development: + - reporting_write + tags: + - notification + summary: Remove event subscription for a specific Report + parameters: + - in: path + name: webhookId + schema: + type: string + required: true + - in: path + name: eventName + schema: + type: string + required: true + responses: + 200: + description: Report deleted from webhook subscription + 401: + description: If no valid access token + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + 403: + description: No permissions to access the resource + content: + application/json: + schema: + $ref: '#/components/schemas/Error' components: schemas: + # report Report: type: object properties: @@ -240,6 +429,66 @@ components: data: type: object + # notification + + Webhook: + type: object + properties: + id: + type: string + format: uuid + name: + type: string + example: wh_aam_digital_reporting + reportSubscriptions: + type: array + items: + type: string + example: [ "report_id_1", "report_id_2", "report_id_3" ] + + WebhookConfiguration: + type: object + properties: + method: + type: string + enum: + - GET + - POST + targetUrl: + type: string + authenticationType: + type: string + enum: + - API_KEY + authentication: + type: object + oneOf: + - $ref: '#/components/schemas/ApiKeyAuthConfig' + + ApiKeyAuthConfig: + type: object + properties: + key: + type: string + headerName: + type: string + + # global + + Error: + type: object + properties: + errorCode: + type: string + items: + enum: + - NOT_FOUND + - UNAUTHORIZED + - FORBIDDEN + - INTERNAL_SERVER_ERROR + errorMessage: + type: string + securitySchemes: development: type: oauth2 @@ -248,5 +497,5 @@ components: clientCredentials: tokenUrl: https://keycloak.aam-digital.net/realms/TolaData/protocol/openid-connect/token scopes: - reports_read: Read Report and ReportCalculation - reports_write: Trigger new ReportCalculation + reporting_read: Read Report and ReportCalculation + reporting_write: Trigger new ReportCalculation and configure webhook notifications From 3871ac1046c2b69c146a6dc3bd83fd45bbd7d32f Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Thu, 8 Feb 2024 17:24:41 +0100 Subject: [PATCH 02/10] docs: add notification-api-v1 spec --- docs/api-specs/reporting-api-v1.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index d1c8af0..8b02c52 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -20,7 +20,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - report summary: Return list of available Reports @@ -44,7 +44,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - report summary: Return report metadata by ID @@ -78,7 +78,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - report summary: Return all report calculations for a report @@ -111,7 +111,7 @@ paths: post: security: - development: - - reporting_write + - reporting_write tags: - report summary: Trigger a new report calculation run. @@ -157,7 +157,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - report summary: Return metadata for a report calculation @@ -193,7 +193,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - report summary: Fetch actual report data for a specific calculation @@ -232,7 +232,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - notification summary: Return list of existing Webhooks @@ -262,7 +262,7 @@ paths: get: security: - development: - - reporting_read + - reporting_read tags: - notification summary: Return a specific Webhook @@ -302,7 +302,7 @@ paths: post: security: - development: - - reporting_write + - reporting_write tags: - notification summary: Subscribe to events for a specific Report @@ -342,7 +342,7 @@ paths: delete: security: - development: - - reporting_write + - reporting_write tags: - notification summary: Remove event subscription for a specific Report From 3816bf0f076c2d74100aa5d8981f668be72279cc Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 09:12:23 +0100 Subject: [PATCH 03/10] Update docs/api-specs/reporting-api-v1.yaml Co-authored-by: Sebastian --- docs/api-specs/reporting-api-v1.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index 8b02c52..cb775ed 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -2,7 +2,8 @@ openapi: 3.0.3 info: title: Aam Digital - Reporting API description: |- - API to manage reports that provide data calculated based on any entities of the Aam Digital system and notifications. + API to manage reports that provide data calculated based on any entities of the Aam Digital system + and offer notifications when data of such reports changes. version: 1.0.0-alpha.2 servers: - url: https://{customerId}.aam-digital.net/api/v1/reporting From 06b9bba94e65164d1d69898034572766d2be1eb7 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 09:14:51 +0100 Subject: [PATCH 04/10] Update docs/api-specs/reporting-api-v1.yaml Co-authored-by: Sebastian --- docs/api-specs/reporting-api-v1.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index cb775ed..14adb19 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -14,7 +14,9 @@ servers: description: Customer ID assigned by the service provider tags: - name: report + description: Access reports and their results and trigger one-time report calculations. - name: notification + description: Subscribe to continuous notification events whenever a report's result data changes due to users changing records in the Aam Digital application. paths: /report: From 1402c7e2aeb7be98dc3347bed938f6229dfe1763 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 09:15:10 +0100 Subject: [PATCH 05/10] Update docs/api-specs/reporting-api-v1.yaml Co-authored-by: Sebastian --- docs/api-specs/reporting-api-v1.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index 14adb19..a2c4eba 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -444,6 +444,7 @@ components: type: string example: wh_aam_digital_reporting reportSubscriptions: + description: The reports for which the webhook will receive a notification event whenever their results change due to users managing data in the Aam Digital system. type: array items: type: string From 17d9415ec7d7d593371994a0695b4e907d86df17 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 09:27:36 +0100 Subject: [PATCH 06/10] Update docs/api-specs/reporting-api-v1.yaml Co-authored-by: Sebastian --- docs/api-specs/reporting-api-v1.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index a2c4eba..049a7b6 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -238,10 +238,10 @@ paths: - reporting_read tags: - notification - summary: Return list of existing Webhooks + summary: Return list of existing Webhooks for your authorized client responses: 200: - description: List of all available Webhooks the requester has created, empty array if no Webhooks are available + description: List of all available Webhooks the requester has created, empty array if no Webhooks are available for the client authorized in the given access token content: application/json: schema: From 2ef54ce8672cfd74524dc3e36004383db6f802e0 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 09:46:41 +0100 Subject: [PATCH 07/10] docs: add event schema --- docs/api-specs/reporting-api-v1.yaml | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index 049a7b6..d2702ff 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -119,7 +119,9 @@ paths: - report summary: Trigger a new report calculation run. description: Trigger a new report calculation run. Check status of the asynchronous calculation via the /report-calculation endpoint - (CURRENTLY UNDER DEVELOPMENT) optionally receive status updates via a webhook if that has been set up for the authorized client + As an alternative to triggering a single report calculation, you can subscribe to receive + a notification event (which includes an automatically created calculationId) whenever the report's + results change (see /webhook/{webhookId}/subscribe/report). parameters: - in: path name: reportId @@ -477,6 +479,25 @@ components: headerName: type: string + Event: + type: object + description: Representation of the payload we will send to the webhook + properties: + id: + type: string + format: uuid + eventName: + type: string + enum: + - NEW_REPORT_DATA_AVAILABLE + reportId: + type: string + calculationId: + type: string + created_at: + type: string + format: date + # global Error: From b916388be99b73a1a6243f68be22cb799df5715e Mon Sep 17 00:00:00 2001 From: Sebastian Date: Fri, 9 Feb 2024 10:18:04 +0100 Subject: [PATCH 08/10] readme --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 96d9152..8520fdf 100644 --- a/README.md +++ b/README.md @@ -54,4 +54,11 @@ This returns a JWT access token required to provided as Bearer Token for any req 2. Request the all available reports: `GET /reports` (see OpenAPI specs for details) 3. Trigger the calculation of a reports data: `POST /report-calculation/` 4. Get status of the report calculation: `GET /report-calculation/` -5. Once the status shows the calculation is completed, get the actual result data: `GET /report-calculation//data` \ No newline at end of file +5. Once the status shows the calculation is completed, get the actual result data: `GET /report-calculation//data` + + +## Subscribe to continous changes of a report +1. Create an initial webhook (if not already registered): `POST /webhook` +2. Register for events of the selected report: `POST /webhook/{webhookId}/subscribe/report/{reportId}:` +3. You will receive Event objects to your webhook, including an initial event directly after you subscribe, pointing to the current report data +4. Use the report-calculation-id in the event to fetch actual data from /report-calculation endpoint \ No newline at end of file From 9778aaca01da879b874c5c4e6dd2743917892300 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 10:54:37 +0100 Subject: [PATCH 09/10] Update docs/api-specs/reporting-api-v1.yaml Co-authored-by: Sebastian --- docs/api-specs/reporting-api-v1.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index d2702ff..203bba8 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -311,6 +311,7 @@ paths: tags: - notification summary: Subscribe to events for a specific Report + description: If you subscribe to a reportId, Aam Digital will continuously monitor the changes users make in the application and check if they affect the results calculcated by that report. Whenever this is the case, a new report-calculation is automatically triggered for you and once the calculation is completed you receive an event containing that calculationId. You can use this to immediately fetch to available report data from the /report-calculation/{calculationId}/data endpoint. Upon subscribing to a report, you will always receive an initial event with a calculationId through which you can access the current state of the report's data. parameters: - in: path name: webhookId From 501b56fb29617f942349a790f8f1bef93a56b4b7 Mon Sep 17 00:00:00 2001 From: Tom Winter Date: Fri, 9 Feb 2024 11:01:07 +0100 Subject: [PATCH 10/10] fix: use user token in report-controller --- README.md | 4 ++-- docs/api-specs/reporting-api-v1.yaml | 10 +++++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8520fdf..d409c07 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,8 @@ This returns a JWT access token required to provided as Bearer Token for any req 5. Once the status shows the calculation is completed, get the actual result data: `GET /report-calculation//data` -## Subscribe to continous changes of a report +## Subscribe to continuous changes of a report 1. Create an initial webhook (if not already registered): `POST /webhook` 2. Register for events of the selected report: `POST /webhook/{webhookId}/subscribe/report/{reportId}:` 3. You will receive Event objects to your webhook, including an initial event directly after you subscribe, pointing to the current report data -4. Use the report-calculation-id in the event to fetch actual data from /report-calculation endpoint \ No newline at end of file +4. Use the report-calculation-id in the event to fetch actual data from /report-calculation endpoint diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index 203bba8..808121b 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -311,7 +311,15 @@ paths: tags: - notification summary: Subscribe to events for a specific Report - description: If you subscribe to a reportId, Aam Digital will continuously monitor the changes users make in the application and check if they affect the results calculcated by that report. Whenever this is the case, a new report-calculation is automatically triggered for you and once the calculation is completed you receive an event containing that calculationId. You can use this to immediately fetch to available report data from the /report-calculation/{calculationId}/data endpoint. Upon subscribing to a report, you will always receive an initial event with a calculationId through which you can access the current state of the report's data. + description: If you subscribe to a reportId, Aam Digital will continuously monitor the changes users + make in the application and check if they affect the results calculated by that report. + Whenever this is the case, a new report-calculation is automatically triggered for you and once + the calculation is completed you receive an event containing that calculationId. You can use + this to immediately fetch to available report data from the /report-calculation/{calculationId}/data + endpoint. Upon subscribing to a report, you will always receive an initial event with a + calculationId through which you can access the current state of the report's data. + externalDocs: + url: https://github.com/Aam-Digital/query-backend/blob/main/README.md#subscribe-to-continuous-changes-of-a-report parameters: - in: path name: webhookId