Merge pull request #194 from camaraproject/x-correlator_guideline_for…

…mat_convention x-correlator_guideline_format_convention
camaraproject · Jun 3, 2024 · e873182 · e873182
2 parents cfa2de9 + afe30cd
commit e873182
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 42 deletions.
diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml
@@ -7,9 +7,22 @@ info:
  license:
   name: Apache 2.0
   url: https://www.apache.org/licenses/LICENSE-2.0.html
- version: 0.4.0
+ version: wip
+
 paths: {}
 components:
+ 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
  schemas:
   TimePeriod:
    properties:
@@ -134,7 +147,7 @@ components:
      example:
       status: 409
       code: CONFLICT
-      message:  Request could not be processed due to a conflict
+      message: Request could not be processed due to a conflict
   FailedPrecondition:
    description: Failed precondition
    content:
@@ -311,7 +324,8 @@ components:
      example:
       status: 406
       code: NOT_ACCEPTABLE
-      message: The server can't produce a response matching the content requested
+      message:
+       The server can't produce a response matching the content requested
        by the client through Accept-* headers
   UnsupportedMediaType:
    description: Unsupported Media Type
@@ -322,5 +336,17 @@ components:
      example:
       status: 415
       code: UNSUPPORTED_MEDIA_TYPE
-      message: The server refuses to accept the request because the payload format
+      message:
+       The server refuses to accept the request because the payload format
        is in an unsupported format.
+  Gone:
+   description: Gone
+   content:
+    application/json:
+     schema:
+      $ref: "#/components/schemas/ErrorInfo"
+     example:
+      status: 410
+      code: GONE
+      message:
+       Access to the target resource is no longer available
diff --git 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:
@@ -90,7 +90,7 @@ paths:
           description: No Content
           headers:
             X-Correlator:
-              $ref: "#/components/headers/X-Correlator"
+              $ref: "#/components/headers/x-correlator"
         400:
           $ref: "#/components/responses/Generic400"
         401:
@@ -99,8 +99,6 @@ paths:
           $ref: "#/components/responses/Generic403"
         410:
           $ref: "#/components/responses/Generic410"
-        415:
-          $ref: "#/components/responses/Generic415"
         429:
           $ref: "#/components/responses/Generic429"
         500:
@@ -112,7 +110,7 @@ components:
     notificationsBearerAuth:
       type: http
       scheme: bearer
-      bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
+      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
   schemas:
     ErrorInfo:
       type: object
@@ -191,13 +189,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:
@@ -207,8 +205,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:
@@ -220,8 +218,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:
@@ -233,8 +231,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:
@@ -246,44 +244,34 @@ components:
     Generic410:
       description: Gone
       headers:
-        X-Correlator:
-          $ref: "#/components/headers/X-Correlator"
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
+            status: 410
             code: GONE
             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:
-            $ref: "#/components/schemas/ErrorInfo"
-          example:
-            code: UNSUPPORTED_MEDIA_TYPE
-            message: "The specified media type is not supported"
     Generic429:
       description: Too Many Requests
       headers:
-        X-Correlator:
-          $ref: "#/components/headers/X-Correlator"
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
+            status: 429
             code: TOO_MANY_REQUESTS
             message: "Endpoint does not support as many requests per time slot"
     Generic500:
       description: Server error
       headers:
-        X-Correlator:
-          $ref: "#/components/headers/X-Correlator"
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -295,8 +283,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:

diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md
@@ -846,11 +846,13 @@ With the aim of standardizing the request observability and traceability process
 
 | Name | Description |  Type | Location | Required by API Consumer | Required in OAS Definition |	Example | 
 |---|---|---|---|---|---|---|
-| `X-Correlator`|	Service correlator to make E2E observability |		String | Request/Response | No | Yes |	b4333c46-49c0-4f62-80d7-f0ef930f1c46 |
+| `x-correlator`|	Service correlator to make E2E observability |		String | Request/Response | No | Yes |	b4333c46-49c0-4f62-80d7-f0ef930f1c46 |
 
-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.
+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.
+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.
+
+NOTE: HTTP headers are case insensitive. The use of the naming `x-correlator` is a guideline to align the format across CAMARA APIs. 
 
 ## 10. Security
 
@@ -1524,7 +1526,7 @@ For consistency across CAMARA APIs, the uniform CloudEvents model must be used w
 | ... | ... | Specific attribute(s) related to the notification event | ... |
 
 
-Note: For operational and troubleshooting purposes it is relevant to accommodate use of `X-Correlator` header attribute. API listener implementations have to be ready to support and receive this data.
+Note: For operational and troubleshooting purposes it is relevant to accommodate use of `x-correlator` header attribute. API listener implementations have to be ready to support and receive this data.
 
 Specific event notification type "subscription-ends" is defined to inform listener about subscription termination. It is used when the `subscriptionExpireTime` or `subscriptionMaxEvents` has been reached, or, if the API server has to stop sending notification prematurely. For this specific event, the `data` must feature `terminationReason` attribute.
 Note: The "subscription-ends" notification is not counted in the `subscriptionMaxEvents`. (for example if a client request a `subscriptionMaxEvents` to 2, later, received 2 notification, then a third notification will be send for "subscription-ends")