diff --git a/README.md b/README.md index 96d9152..d409c07 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 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 diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml index e72b67e..808121b 100644 --- a/docs/api-specs/reporting-api-v1.yaml +++ b/docs/api-specs/reporting-api-v1.yaml @@ -2,8 +2,9 @@ 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 offer notifications when data of such reports changes. + version: 1.0.0-alpha.2 servers: - url: https://{customerId}.aam-digital.net/api/v1/reporting description: Developer Instance for testing @@ -13,13 +14,16 @@ 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: get: security: - development: - - reports_read + - reporting_read tags: - report summary: Return list of available Reports @@ -34,12 +38,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 +66,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,18 +100,28 @@ 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. 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 @@ -127,12 +153,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 +183,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 +210,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 +220,176 @@ 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 for your authorized client + responses: + 200: + 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: + 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 + 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 + 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 +443,86 @@ components: data: type: object + # notification + + Webhook: + type: object + properties: + id: + type: string + format: uuid + name: + 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 + 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 + + 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: + type: object + properties: + errorCode: + type: string + items: + enum: + - NOT_FOUND + - UNAUTHORIZED + - FORBIDDEN + - INTERNAL_SERVER_ERROR + errorMessage: + type: string + securitySchemes: development: type: oauth2 @@ -248,5 +531,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