Add X-Correlator and other fixes

code/API_definitions/qod-api.yaml

@@ -66,7 +66,7 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.10.1
+  version: wip
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
@@ -108,6 +108,8 @@ paths:
         for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
 
       operationId: createSession
+      parameters:
+        - $ref: "#/components/parameters/x-correlator"
       requestBody:
         description: Parameters to create a new session
         content:
@@ -127,6 +129,8 @@ paths:
                 The QoD server will call this endpoint whenever any QoS session change (e.g. network termination) related event occurs.
                 Currently only QOS_STATUS_CHANGED event is defined.
               operationId: postNotification
+              parameters:
+                - $ref: "#/components/parameters/x-correlator"
               requestBody:
                 required: true
                 content:
@@ -139,6 +143,9 @@ paths:
               responses:
                 "204":
                   description: Successful notification
+                  headers:
+                    x-correlator:
+                      $ref: '#/components/headers/x-correlator'
                 "400":
                   $ref: "#/components/responses/Generic400"
                 "401":
@@ -155,12 +162,18 @@ paths:
       responses:
         "201":
           description: Session created
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/SessionInfo"
         "400":
           description: Invalid input for createSession operation
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -232,6 +245,9 @@ paths:
           $ref: "#/components/responses/Generic403"
         "409":
           description: Conflict
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -265,9 +281,13 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/SessionId"
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "200":
           description: Contains information about active session
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -308,9 +328,13 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/SessionId"
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "204":
           description: Session deleted
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -350,6 +374,7 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/SessionId"
+        - $ref: "#/components/parameters/x-correlator"
       requestBody:
         description: Parameters to extend the duration of an active session
         content:
@@ -360,12 +385,18 @@ paths:
       responses:
         "200":
           description: Contains information about active session
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/SessionInfo"
         "400":
           description: Invalid input for extendQosSessionDuration operation
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -416,12 +447,17 @@ paths:
           required: false
         - name: status
           in: query
+          description: Qos Profile status
           schema:
             $ref: '#/components/schemas/QosProfileStatusEnum'
           required: false
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "200":
           description: Contains information about QoS Profiles
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -450,12 +486,17 @@ paths:
       parameters:
         - name: name
           in: path
+          description: Qos Profile name
           required: true
           schema:
             $ref: "#/components/schemas/QosProfileName"
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "200":
           description: Contains information about QoS Profiles
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
           content:
             application/json:
               schema:
@@ -484,6 +525,7 @@ components:
           tokenUrl: https://api.example.com/oauth/token
           scopes: {}
     notificationsBearerAuth:
+      description: Bearer authentication for notifications
       type: http
       scheme: bearer
       bearerFormat: "{$request.body#/webhook/notificationAuthToken}"
@@ -500,6 +542,20 @@ components:
             qod-sessions-delete: Deletion of QoS sessions
             qod-profiles-read: Retrieval of QoS profiles
 
+  parameters:
+    x-correlator:
+      name: x-correlator
+      in: header
+      description: Correlation id for the different services
+      schema:
+        type: string
+
+  headers:
+    x-correlator:
+      description: Correlation id for the different services
+      schema:
+        type: string
+
   schemas:
     SessionId:
       description: Session ID in UUID format
@@ -525,6 +581,7 @@ components:
         qosProfile:
           $ref: "#/components/schemas/QosProfileName"
         webhook:
+          description: Callback URL on which notifications about all status change events of the session (eg. session termination) can be received
           type: object
           required:
             - notificationUrl
@@ -608,10 +665,12 @@ components:
       maximum: 65535
 
     PortsSpec:
+      description: Specification of several TCP or UDP ports
       type: object
       minProperties: 1
       properties:
         ranges:
+          description: Range of TCP or UDP ports
           type: array
           minItems: 1
           items:
@@ -625,6 +684,7 @@ components:
               to:
                 $ref: "#/components/schemas/Port"
         ports:
+          description: Array of TCP or UDP ports
           type: array
           minItems: 1
           items:
@@ -808,9 +868,11 @@ components:
       pattern: "^[a-zA-Z0-9_.-]+$"
 
     Rate:
+      description: Specification of rate
       type: object
       properties:
         value:
+          description: Quantity of rate
           type: integer
           example: 10
           format: int32
@@ -820,19 +882,20 @@ components:
           $ref: "#/components/schemas/RateUnitEnum"
 
     Duration:
+      description: Specification of duration
       type: object
       properties:
         value:
+          description: Quantity of duration
           type: integer
           example: 12
           format: int32
           minimum: 1
         unit:
-          allOf:
-            - $ref: "#/components/schemas/TimeUnitEnum"
-            - example: Minutes
+          $ref: "#/components/schemas/TimeUnitEnum"
 
     TimeUnitEnum:
+      description: Units of time
       type: string
       enum:
         - Days
@@ -856,6 +919,7 @@ components:
         - DEPRECATED
 
     RateUnitEnum:
+      description: Units of rate
       type: string
       enum:
         - bps
@@ -909,6 +973,7 @@ components:
           org.camaraproject.qod.v0.qos-status-changed: '#/components/schemas/EventQosStatusChanged'
 
     EventQosStatusChanged:
+      description: Event to notify a QoS status change
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
@@ -1056,6 +1121,7 @@ components:
             - 2001:db8:85a3:8d3::/64
 
     Message:
+      description: Message with additional information
       type: object
       properties:
         severity:
@@ -1092,6 +1158,7 @@ components:
         - UNAVAILABLE
 
     ErrorInfo:
+      description: Common schema for errors
       type: object
       properties:
         status:
@@ -1111,6 +1178,9 @@ components:
   responses:
     Generic400:
       description: Invalid input
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1122,6 +1192,9 @@ components:
 
     Generic401:
       description: Unauthorized
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1133,6 +1206,9 @@ components:
 
     Generic403:
       description: Forbidden
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1144,6 +1220,9 @@ components:
 
     SessionNotFound404:
       description: Session not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1155,6 +1234,9 @@ components:
 
     QosProfilesNotFound404:
       description: Qos Profiles not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1166,6 +1248,9 @@ components:
 
     QosProfileNotFound404:
       description: Qos Profile not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1177,6 +1262,9 @@ components:
 
     Generic500:
       description: Internal server error
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1188,6 +1276,9 @@ components:
 
     QoSProfile500:
       description: Internal server error
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1199,6 +1290,9 @@ components:
 
     Generic501:
       description: Not Implemented
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1210,6 +1304,9 @@ components:
 
     Generic503:
       description: Service unavailable
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
@@ -1221,7 +1318,8 @@ components:
 
   examples:
     QOS_STATUS_CHANGED_EXAMPLE:
-      summary: QoS status changed
+      description: QoS status changed
+      summary: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
       value:
         id: 83a0d986-0866-4f38-b8c0-fc65bfcda452
         source: 'https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000'