From 55911f2c7b54f645b968d7366f45b4cc405e0e82 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 1 Apr 2024 16:54:30 +0200 Subject: [PATCH 1/2] x-correlator_support_guidelines_in_notifications --- artifacts/notification-as-cloud-event.yaml | 54 +++++++++++++++++++++- documentation/API-design-guidelines.md | 2 + 2 files changed, 54 insertions(+), 2 deletions(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 5a44e4c8..523db9fd 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -57,14 +57,14 @@ servers: default: https://localhost:8080 description: Can be any notification server address sent by the client application tags: - - name: Cloud Event + - name: CAMARA Cloud Event description: | Events received on subscription listener side. paths: /your_webhook_notification_url: post: tags: - - CAMARA Cloud Event notification endpoint + - CAMARA Cloud Event summary: "Cloud Event notification endpoint to notify consumer that statement of fact had occurred" description: | INFORMATIVE ENDPOINT: The value of this endpoint is freely declared by each client app by means of resource-based @@ -73,6 +73,8 @@ paths: in the triggering of the procedure (resource-based or instance-based). In this way, it represents an absolute URL, i.e.: notifications won't be sent to /event-notification/vX/your_webhook_notification_url. operationId: sendEvent + parameters: + - $ref: "#/components/parameters/x-correlator" requestBody: required: true content: @@ -86,12 +88,24 @@ paths: responses: 201: description: Created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" 202: description: Accepted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" 204: description: No Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" 200: description: Ok + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -192,10 +206,25 @@ components: description: Event details payload described in each CAMARA API and referenced by its type time: $ref: "#/components/schemas/DateTime" + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string responses: Generic400: description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -206,6 +235,9 @@ components: message: "Client specified an invalid argument, request body or query param" Generic401: description: Authentication problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -216,6 +248,9 @@ components: message: "Request not authenticated due to missing, invalid, or expired credentials" Generic403: description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -226,6 +261,9 @@ components: message: "Client does not have sufficient permissions to perform this action" Generic410: description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -235,6 +273,9 @@ components: message: "Access to the target resource is no longer available." Generic415: description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -244,6 +285,9 @@ components: message: "The specified media type is not supported" Generic429: description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -253,6 +297,9 @@ components: message: "Endpoint does not support as many requests per time slot" Generic500: description: Server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -263,6 +310,9 @@ components: message: "Server error" Generic503: description: Service unavailable. Typically the server is down. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 5bb0d3ff..7aee2d71 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -850,6 +850,8 @@ With the aim of standardizing the request observability and traceability process When the API Consumer includes the "X-Correlator" header in the request, the API provider must include it in the response with the same UUID as was used in the request. Otherwise, it is optional to include the "X-Correlator" header in the response with any valid (preferably randomly chosen) UUID. +In notification scenarios (i.e. POST request sent towards the listener to the `webhook.notificationUrl` indicated), the use of the "X-Correlator" is supported for the same aim as well. When the API request includes the "X-Correlator" header, it is recommended for the listener to include it in the response with the same value as was used in the request. Otherwise, it is optional to include the "X-Correlator" header in the response with any valid value. + ## 10. Security One of the key points in the API definition process is to specify and validate the security needs that will be maintained to guarantee data integrity and access control. There are multiple ways to secure a RESTful API, e.g. basic authentication, OAuth, etc., but one thing is for sure: RESTful APIs should be stateless, so authentication/authorization requests should not rely on cookies or sessions. Instead, each API request must come with some form of authentication credentials that must be validated on the server for each request. From 455451d1f9911a8fbe946af1487d19472258481c Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 2 Apr 2024 12:19:32 +0200 Subject: [PATCH 2/2] x-correlator_naming_alignment --- artifacts/notification-as-cloud-event.yaml | 56 +++++++++++----------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 523db9fd..b97204ee 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -74,7 +74,7 @@ paths: URL, i.e.: notifications won't be sent to /event-notification/vX/your_webhook_notification_url. operationId: sendEvent parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: "#/components/parameters/X-Correlator" requestBody: required: true content: @@ -89,23 +89,23 @@ paths: 201: description: Created headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" 202: description: Accepted headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" 204: description: No Content headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" 200: description: Ok headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -207,13 +207,13 @@ components: time: $ref: "#/components/schemas/DateTime" headers: - x-correlator: + X-Correlator: description: Correlation id for the different services schema: type: string parameters: - x-correlator: - name: x-correlator + X-Correlator: + name: X-Correlator in: header description: Correlation id for the different services schema: @@ -223,8 +223,8 @@ components: Generic400: description: Problem with the client request headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -236,8 +236,8 @@ components: Generic401: description: Authentication problem with the client request headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -249,8 +249,8 @@ components: Generic403: description: Client does not have sufficient permission headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -262,8 +262,8 @@ components: Generic410: description: Gone headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -274,8 +274,8 @@ components: Generic415: description: Unsupported Media Type headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -286,8 +286,8 @@ components: Generic429: description: Too Many Requests headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -298,8 +298,8 @@ components: Generic500: description: Server error headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: @@ -311,8 +311,8 @@ components: Generic503: description: Service unavailable. Typically the server is down. headers: - x-correlator: - $ref: "#/components/headers/x-correlator" + X-Correlator: + $ref: "#/components/headers/X-Correlator" content: application/json: schema: