API aligment with Commonalities

code/API_definitions/blockchain_public_address.yaml → code/API_definitions/blockchain-public-address.yaml

@@ -18,28 +18,31 @@ info:
      - **Endpoint to associate a mobile phone number with a Blockchain Public Address**. It does not matter if the mobile phone number is already bound to a Blockchain Public Address, as this operation adds a new Blockchain Public Address. This operation is intended to be used with a 3-legged Access Token, and the indicated mobile phone number must belong to the sub in the Access Token; this is because only the user of the mobile phone number must be able to perform a bind. As a consequence, this operation will only work with mobile phone numbers of the Telco Operator exposing the API.
      - **Endpoint to remove the association of a mobile phone number with a Blockchain Public Address**. This operation is intended to be used with a 3-legged Access Token; this is because only the user of the mobile phone number must be able to perform an unbind. Note: Due to this, the API Server must validate that the `id` included in the request refers to a bind for a mobile phone number belonging to the `sub` in the Access Token. As a consequence, this operation will only work with mobile phone numbers of the Telco Operator exposing the API.
 
+    # Authorization and authentication
+
+    The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile.
+
+    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+
+    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
+
     # Further Info and Support
 
     (FAQs will be added in a later version of the documentation)
-  termsOfService: http://swagger.io/terms/
-  contact:
-    email: [email protected]
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.2.0-wip
+  version: wip
+  x-camara-commonalities: 0.4.0
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
 servers:
-  - url: "{apiRoot}/{basePath}"
+  - url: "{apiRoot}/blockchain-public-address/vwip"
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root
-      basePath:
-        default: blockchain-public-address/v0
-        description: Base path for the Blockchain Public Address API
+        description: API root, defined by the service provider
 tags:
   - name: Blockchain Public Address
     description: API operations to manage Blockchain Public Addresses
@@ -215,7 +218,7 @@ components:
     PhoneNumber:
       name: phoneNumber
       in: query
-      description: A mobile phone number belonging to the user. In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
+      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
       required: true
       schema:
         type: string
@@ -230,7 +233,7 @@ components:
       properties:
         phoneNumber:
           type: string
-          description: Mobile phone number to which the Blockchain Public Address will be bound. In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
+          description: Mobile phone number to which the Blockchain Public Address will be bound. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
         blockchainPublicAddress:
           type: string
           description: User's Blockchain Public Address to bind to the mobile `phoneNumber`
@@ -341,22 +344,26 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
-            InvalidArgument:
+            GENERIC_400_INVALID_ARGUMENT:
+              description: Invalid Argument. Generic Syntax Exception
               value:
                 status: 400
                 code: INVALID_ARGUMENT
-                message: Client specified an invalid argument, request body or query param
-            InvalidBlockchainNetworkId:
+                message: Client specified an invalid argument, request body or query param.
+            GENERIC_400_INVALID_BLOCKCHAIN_NETWORK_ID:
+              description: blockchainNetworkId is not valid
               value:
                 status: 400
                 code: BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_BLOCKCHAIN_NETWORK_IDENTIFIER
                 message: Indicated blockchainNetworkId is not valid
-            InvalidCurrencyForBlockchain:
+            GENERIC_400_INVALID_CURRENCY_FOR_BLOCKCHAIN:
+              description: Invalid currency
               value:
                 status: 400
                 code: BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY
                 message: Indicated currency is not found
-            RequiredCurrencyForBlockchain:
+            GENERIC_400_REQUIRED_CURRENCY_FOR_BLOCKCHAIN:
+              description: Currency is required
               value:
                 status: 400
                 code: BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED
@@ -374,12 +381,14 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
-            PermissionDenied:
+            GENERIC_403_PERMISSION_DENIED:
+              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
               value:
                 status: 403
                 code: PERMISSION_DENIED
-                message: "Operation not allowed: ..."
-            NotAllowedBlockchainNetworkId:
+                message: Client does not have sufficient permissions to perform this action.
+            GENERIC_403_NOT_ALLOWED_BLOCKCHAIN_NETWORK_ID:
+              description: blockchainNetworkId not allowed by business rules
               value:
                 status: 403
                 code: BLOCKCHAIN_PUBLIC_ADDRESS.BLOCKCHAIN_NETWORK_IDENTIFIER_NOT_ALLOWED
@@ -393,23 +402,35 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 400
-            code: INVALID_ARGUMENT
-            message: Client specified an invalid argument, request body or query param
+          examples:
+            GENERIC_400_INVALID_ARGUMENT:
+              description: Invalid Argument. Generic Syntax Exception
+              value:
+                status: 400
+                code: INVALID_ARGUMENT
+                message: Client specified an invalid argument, request body or query param.
     Generic401:
-      description: Authentication problem with the client request
+      description: Unauthorized
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 401
-            code: UNAUTHENTICATED
-            message: Request not authenticated due to missing, invalid, or expired credentials
+          examples:
+            GENERIC_401_UNAUTHENTICATED:
+              description: Request cannot be authenticated
+              value:
+                status: 401
+                code: UNAUTHENTICATED
+                message: Request not authenticated due to missing, invalid, or expired credentials.
+            GENERIC_401_AUTHENTICATION_REQUIRED:
+              description: New authentication is needed, authentication is no longer valid
+              value:
+                status: 401
+                code: AUTHENTICATION_REQUIRED
+                message: New authentication is required.
     Generic403:
       description: Forbidden
       headers:
@@ -419,10 +440,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 403
-            code: PERMISSION_DENIED
-            message: "Operation not allowed: ..."
+          examples:
+            GENERIC_403_PERMISSION_DENIED:
+              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action.
     Generic404:
       description: Not found
       headers:
@@ -432,10 +456,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 404
-            code: NOT_FOUND
-            message: The specified resource is not found
+          examples:
+            GENERIC_404_NOT_FOUND:
+              description: Resource is not found
+              value:
+                status: 404
+                code: NOT_FOUND
+                message: The specified resource is not found.
     Generic409:
       description: Conflict
       headers:
@@ -445,10 +472,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 409
-            code: ALREADY_EXISTS
-            message: "A specified resource duplicate entry found"
+          examples:
+            GENERIC_409_ALREADY_EXISTS:
+              description: Trying to create an existing resource
+              value:
+                status: 409
+                code: ALREADY_EXISTS
+                message: The resource that a client tried to create already exists.
     Generic429:
       description: Too Many Requests
       headers:
@@ -458,10 +488,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 429
-            code: TOO_MANY_REQUESTS
-            message: Either out of resource quota or reaching rate limiting
+          examples:
+            GENERIC_429_TOO_MANY_REQUESTS:
+              description: API Server request limit is overpassed
+              value:
+                status: 429
+                code: TOO_MANY_REQUESTS
+                message: Either out of resource quota or reaching rate limiting.
     Generic500:
       description: Server error
       headers:
@@ -471,10 +504,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 500
-            code: INTERNAL
-            message: Server error
+          examples:
+            GENERIC_500_INTERNAL:
+              description: Problem in Server side. Regular Server Exception
+              value:
+                status: 500
+                code: INTERNAL
+                message: Unknown server error. Typically a server bug.
     Generic503:
       description: Service unavailable
       headers:
@@ -484,10 +520,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 503
-            code: UNAVAILABLE
-            message: Service unavailable
+          examples:
+            GENERIC_503_UNAVAILABLE:
+              description: Service is not available. Temporary situation usually related to maintenance process in the server side
+              value:
+                status: 503
+                code: UNAVAILABLE
+                message: Service Unavailable.
     Generic504:
       description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
       headers:
@@ -497,7 +536,10 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 504
-            code: TIMEOUT
-            message: Request timeout exceeded
+          examples:
+            GENERIC_504_TIMEOUT:
+              description: API Server Timeout
+              value:
+                status: 504
+                code: TIMEOUT
+                message: Request timeout exceeded.