Update TI API for Consent Management - xcorrelator - Errors

- Added openId authentication for Consent Management - Aligment with guidelines: - added xcorrelator - aligned returned Errors
camaraproject · Apr 10, 2024 · 7962598 · 7962598
1 parent 32c7ca4
commit 7962598
Showing 1 changed file with 166 additions and 41 deletions.
diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml
@@ -96,15 +96,6 @@ externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
 
-
-############################################################################
-#                                     Security                             #
-############################################################################
-security:
-  - oAuth2:
-      - 'edge:traffic-influences:read'
-      - 'edge:traffic-influences:write'
-
 ############################################################################
 #                                     Servers                              #
 ############################################################################
@@ -135,7 +126,11 @@ tags:
 paths:
   /traffic-influences:
     get:
+      security:
+        - openId:
+          - traffic-influences:read    
       parameters:
+        - $ref: '#/components/parameters/x-correlator'      
         - in: query
           name: appId
           schema:
@@ -144,11 +139,14 @@ paths:
       tags:
         - Traffic Influence API read
       summary: Retries existing TrafficInfluence Resources
-      description: Reads all of the active TrafficInfluence resources owned by the same API Consumer authenticated via oAuth2
+      description: Reads all of the active TrafficInfluence resources owned by the same API Consumer
       operationId: getTrafficInfluence
       responses:
         '200':
           description: Returns the information about existing TrafficInfluence resources. 
+          headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'          
           content:
             application/json:
               schema:
@@ -172,18 +170,24 @@ paths:
       summary: Creates a new TrafficInfluence resource
       description: Takes as input an object containing the intents from the API Consumer and creates a TrafficInfluence resourse accordingly. The trafficInfluenceID parameter, that is part of the object, must not be valorized when creating a new resource. For this reason the trafficInfluenceID parameter must be avoided in the object, anyway it will be ignored by the API Producer. It is automatically generated by the system and returned in the response.
       operationId: postTrafficInfluence
+      parameters:
+        - $ref: '#/components/parameters/x-correlator'      
+      security:
+        - openId:
+          - traffic-influences:write       
       requestBody:
         description: Describes the request body
         required: true
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/PostTrafficInfluence'
-
       responses:
         '201':
-          description: TrafficInfluence resource created, the related object is returned with the resource ID (trafficInfluenceID) and status (state) valorised, 
+          description: TrafficInfluence resource created, the related object is returned with the resource ID (trafficInfluenceID) and status (state) valorised. 
           headers:
+            x-correlator:
+              $ref: '#/components/headers/x-correlator'
             Location:
               description: Link to the created traffic influence resource
               schema:
@@ -221,11 +225,19 @@ paths:
       tags:
         - Traffic Influence API read
       summary: Reads a specific TrafficInfluence resource identified by the trafficInfluenceID value
-      description: Returns a specific TrafficInfluence resources owned by the same API Consumer authenticated via oAuth2
+      description: Returns a specific TrafficInfluence resources owned by the same API Consumer
       operationId: getAllTrafficInfluences
+      parameters:
+        - $ref: '#/components/parameters/x-correlator'        
+      security:
+        - openId:
+          - traffic-influences:read 
       responses:
         '200':
           description: OK. 
+          headers:
+            x-correlator:
+             $ref: '#/components/headers/x-correlator'        
           content:
             application/json:
               schema:
@@ -248,6 +260,11 @@ paths:
       summary: updates a specific TrafficInfluence resource, identified by the trafficInfluenceID value
       description: The resource identified by the trafficInfluenceID value can be modified
       operationId: patchTrafficInfluence
+      parameters:
+        - $ref: '#/components/parameters/x-correlator'          
+      security:
+        - openId:
+          - traffic-influences:write       
       requestBody:
         description: Describes the request body
         required: true
@@ -268,6 +285,8 @@ paths:
               schema:
                 type: string
                 description: Link to the created traffic influence resource
+            x-correlator:
+             $ref: '#/components/headers/x-correlator'                 
         "400":
           $ref: "#/components/responses/Generic400"   
         '404':
@@ -291,7 +310,11 @@ paths:
       summary: Delete an existing TrafficInfluence resource
       description: invoked by the API Consumer to stop influencing the traffic, deleting a TrafficInfluence resource previously created
       operationId: deleteTrafficInfluence      
+      security:
+        - openId:
+          - traffic-influences:write      
       parameters:
+        - $ref: '#/components/parameters/x-correlator'        
         - name: callbackUrl
           in: query
           required: false
@@ -318,18 +341,30 @@ paths:
       callbacks:
         onTrafficInfluenceChanged:
           $ref: "#/components/callbacks/onTrafficInfluenceChanged"
-
+
+#######################################################
+#  COMPONENTS
+#######################################################
+
 components:
   securitySchemes:
-    oAuth2:    
-      type: oauth2
-      description: This API uses OAuth 2 [More info](https://api.example.com/docs/auth)
-      flows:        
-        clientCredentials:
-          tokenUrl: 'https://example.com/oauth/token'
-          scopes:
-            'edge:traffic-influences:read': Grant read-only traffic-influences data
-            'edge:traffic-influences:write': Grant write access to traffic-influences data
+    openId:
+      type: openIdConnect
+      openIdConnectUrl: https://example.com/.well-known/openid-configuration
+
+  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
 
  #######################################################
  #  EVENTS/CALLBACKS
@@ -344,7 +379,9 @@ components:
                 - Traffic Influence CALLBACK Operation
               summary: Provides a notifican channel for changes in the TrafficInfluence resource
               description: Creating, modifying or delating a Traffic Influece resourece is an asycronous task. For this reason a notification channel via callback to a specified URL is provided.
-              operationId: postTrafficInfluence            
+              operationId: postTrafficInfluence     
+              parameters:
+                - $ref: '#/components/parameters/x-correlator'                
               requestBody:
                 description: subscription payload which contains the updated traffic influence instance
                 content:
@@ -356,10 +393,16 @@ components:
                     description: |
                       Your server implementation should return this HTTP status code
                       if the data was received successfully
+                    headers:
+                      x-correlator:
+                        $ref: '#/components/headers/x-correlator'                      
                   '204':
                     description: |
                       Your server should return this HTTP status code if no longer interested
                       in further updates
+                    headers:
+                      x-correlator:
+                        $ref: '#/components/headers/x-correlator'                         
  #######################################################
  #  RESOURCES
  #######################################################
@@ -531,7 +574,7 @@ components:
           type: string
           example: OK
     ErrorInfo:
-      description: Information in case of errors    
+      description: Information in case of error  
       type: object
       required:
         - code
@@ -546,6 +589,9 @@ components:
   responses:
     ResNotFound:
       description: The specified resource was not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'      
       content:
         application/json:
           schema:
@@ -555,6 +601,9 @@ components:
             message: Resource not found
     GenericError:
       description: An unknow error has occurred
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'      
       content:
         application/json:
           schema:
@@ -564,6 +613,9 @@ components:
             message: Generic error
     BackendConnTimeout:
       description: Connection timeout towards backend service has occurred
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'      
       content:
         application/json:
           schema:
@@ -573,44 +625,117 @@ components:
             message: Backend connection timeout
     OkDeletionInProgress:
       description: The resource delation request has been accepted
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'      
       content:
         application/json:
+          schema:
+            $ref: '#/components/schemas/ErrResponse'        
           example:
             status: OK
             message: Accepted
     Generic400:
-      description: Invalid input
+      description: Problem with the client request
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/ErrorInfo"
+            $ref: '#/components/schemas/ErrorInfo'
           example:
-            code: INVALID_INPUT
-            message: "Schema validation failed at  ..."
+            status: 400
+            code: INVALID_ARGUMENT
+            message: Client specified an invalid argument, request body or query param
+
     Generic401:
-      description: Unauthorized
+      description: Authentication problem with the client request
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/ErrorInfo"
+            $ref: '#/components/schemas/ErrorInfo'
           example:
-            code: UNAUTHORIZED
-            message: "Authorization failed: ..."
+            status: 401
+            code: UNAUTHENTICATED
+            message: Request not authenticated due to missing, invalid, or expired credentials
+
     Generic403:
-      description: Forbidden
+      description: Client does not have sufficient permission
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            PermissionDenied:
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action
+            InvalidTokenContext:
+              value:
+                status: 403
+                code: INVALID_TOKEN_CONTEXT
+                message: Phone number cannot be deducted from access token context
+
+    Generic404:
+      description: The specified resource was not found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 404
+            code: CALL_FORWARDING.UNKNOWN_PHONE_NUMBER
+            message: Call forwarding check can't be done because the phone number is unknown
+
+    Generic500:
+      description: Server error
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/ErrorInfo"
+            $ref: '#/components/schemas/ErrorInfo'
           example:
-            code: FORBIDDEN
-            message: "Operation not allowed: ..."
+            status: 500
+            code: INTERNAL
+            message: Server error
+
     Generic503:
-      description: Service unavailable
+      description: Service unavailable. Typically the server is down
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          example:
+            status: 503
+            code: UNAVAILABLE
+            message: Service unavailable
+
+    Generic504:
+      description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/ErrorInfo"
+            $ref: '#/components/schemas/ErrorInfo'
           example:
-            code: SERVICE_UNAVALIBLE
-            message: "Service unavailable"
+            status: 504
+            code: TIMEOUT
+            message: Request timeout exceeded. Try later