diff --git a/code/API_definitions/blockchain_public_address.yaml b/code/API_definitions/blockchain-public-address.yaml similarity index 78% rename from code/API_definitions/blockchain_public_address.yaml rename to code/API_definitions/blockchain-public-address.yaml index 049749d..8058222 100644 --- a/code/API_definitions/blockchain_public_address.yaml +++ b/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: project-email@sample.com 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,12 +402,15 @@ 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' @@ -406,10 +418,19 @@ components: 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.