From f7732b9d58d2bd89fd7b624e8b0868b557bb7f2f Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Wed, 27 Nov 2024 15:37:05 +0900 Subject: [PATCH 1/7] Update error codes and description --- code/API_definitions/number-recycling.yaml | 40 ++++++++-------------- 1 file changed, 15 insertions(+), 25 deletions(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index 3ba665e..47c685b 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -50,29 +50,19 @@ info: 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. - # Identifying a phone number from the access token + # Identifying the phone number from the access token - This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API. + This API requires the API consumer to identify a phone number as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. - ## Handling of phone number information: +This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ### Optional `phoneNumber` field for 3-legged tokens: + ### Error handling: - - When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_PHONE_NUMBER` error code. + - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. - ### Validation mechanism: - - - The server will extract the phone number identification from the access token, if available. - - If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number provided matches the one associated with the access token. - - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token. - - ### Error handling for unidentifiable phone number: - - - If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error. - - ### Restrictions for tokens without an associated authenticated phone number: - - For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens. version: wip x-camara-commonalities: 0.4.0 @@ -244,11 +234,6 @@ components: status: 403 code: PERMISSION_DENIED detail: Client does not have sufficient permissions to perform this action - InvalidTokenContext: - value: - status: 403 - code: INVALID_TOKEN_CONTEXT - detail: Phone number cannot be deducted from access token context Generic404: description: Resource Not Found headers: @@ -281,10 +266,15 @@ components: status: 422 code: NOT_SUPPORTED detail: Service not supported for this phoneNumber - UnidentifiablePhoneMumber: + UnnecessaryPhoneNumber: + value: + status: 422 + code: UNNECESSARY_PHONE_NUMBER + detail: Service not supported for this phoneNumber + MissingPhoneMumber: value: status: 422 - code: UNIDENTIFIABLE_PHONE_NUMBER + code: MISSING_PHONE_NUMBER detail: The phone number cannot be identified Generic500: description: Server error From d482b02744ff6551c8f14bc0f7a6ea4d04ad3233 Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Wed, 27 Nov 2024 15:51:21 +0900 Subject: [PATCH 2/7] Error correction for description --- code/API_definitions/number-recycling.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index 47c685b..a96e044 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -58,7 +58,7 @@ info: This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ### Error handling: + ### Error handling - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_PHONE_NUMBER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. From 6d589f375e2b1b1d2cef57ab95f256c595e0b1bd Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Wed, 27 Nov 2024 15:57:31 +0900 Subject: [PATCH 3/7] Error correction for description rev2 --- code/API_definitions/number-recycling.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index a96e044..5345894 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -58,7 +58,7 @@ info: This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ### Error handling + ## Error handling: - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_PHONE_NUMBER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. From e4e3b231cfb2f91debd3d693494a546d5bb7e972 Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Wed, 27 Nov 2024 16:13:27 +0900 Subject: [PATCH 4/7] Error correction for description rev3 --- code/API_definitions/number-recycling.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index 5345894..401f6c9 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -58,7 +58,7 @@ info: This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ## Error handling: + ## Error handling: - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_PHONE_NUMBER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. From 01f70110647397102fc11e79c280f4d7eded7e4c Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Wed, 27 Nov 2024 16:23:59 +0900 Subject: [PATCH 5/7] Error correction for description rev4 --- code/API_definitions/number-recycling.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index 401f6c9..67dfc9b 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -56,9 +56,9 @@ info: - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. -This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ## Error handling: + ## Error handling: - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_PHONE_NUMBER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. From 463df854fb22f785ded2e564cabbd60fe4836470 Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Thu, 28 Nov 2024 21:43:54 +0900 Subject: [PATCH 6/7] Correction for error codes --- code/API_definitions/number-recycling.yaml | 30 +++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index 67dfc9b..efe5bcc 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -201,7 +201,7 @@ components: example: status: 400 code: INVALID_ARGUMENT - detail: Client specified an invalid argument, request body or query param + message: Request body does not comply with the schema Generic401: description: Authentication problem with the client request headers: @@ -216,7 +216,7 @@ components: example: status: 401 code: UNAUTHENTICATED - detail: Request not authenticated due to missing, invalid, or expired credentials + message: Request not authenticated due to missing, invalid, or expired credentials Generic403: description: Client does not have sufficient permission headers: @@ -233,7 +233,7 @@ components: value: status: 403 code: PERMISSION_DENIED - detail: Client does not have sufficient permissions to perform this action + message: Client does not have sufficient permissions to perform this action Generic404: description: Resource Not Found headers: @@ -248,7 +248,7 @@ components: example: status: 404 code: NOT_FOUND - detail: A specified resource is not found + message: A specified resource is not found Generic422: description: Unprocessable Content headers: @@ -261,21 +261,21 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - NotSupported: + DeviceNotApplicable: value: status: 422 - code: NOT_SUPPORTED - detail: Service not supported for this phoneNumber - UnnecessaryPhoneNumber: + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided phone number + UnnecessaryIdentifier: value: status: 422 - code: UNNECESSARY_PHONE_NUMBER - detail: Service not supported for this phoneNumber - MissingPhoneMumber: + code: UNNECESSARY_IDENTIFIER + message: The phone number is already identified by the access token + MissingIdentifier: value: status: 422 - code: MISSING_PHONE_NUMBER - detail: The phone number cannot be identified + code: MISSING_IDENTIFIER + message: The phone number cannot be identified Generic500: description: Server error headers: @@ -290,7 +290,7 @@ components: example: status: 500 code: INTERNAL - detail: Server error + message: Unknown server error. Typically a server bug. Generic503: description: Service unavailable. Typically the server is down. headers: @@ -305,4 +305,4 @@ components: example: status: 503 code: UNAVAILABLE - detail: Service unavailable + message: Service unavailable From 53f5879410572d2a451406729dfe2076cf424311 Mon Sep 17 00:00:00 2001 From: Kenichi Yamamoto Date: Thu, 28 Nov 2024 22:06:28 +0900 Subject: [PATCH 7/7] Correction for error codes v01 --- code/API_definitions/number-recycling.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/number-recycling.yaml b/code/API_definitions/number-recycling.yaml index efe5bcc..4dfbf14 100644 --- a/code/API_definitions/number-recycling.yaml +++ b/code/API_definitions/number-recycling.yaml @@ -164,7 +164,7 @@ components: required: - status - code - - detail + - message properties: status: type: integer @@ -172,9 +172,9 @@ components: code: type: string description: Code given to this error - detail: + message: type: string - description: Detailed error description + description: A human readable description of what the event represent responses: Generic200: description: OK