Merge pull request #170 from camaraproject/x-correlator_support_guide…

…lines_in_notifications

x-correlator_support_guidelines_in_notifications

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:

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 value that was used in the request. Otherwise, it is optional to include the "X-Correlator" header in the response with any valid value. Recommendation is to use UUID for values.
 
+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.