From 4362de5746518a7230d897a7d3e2347c2ac00787 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 30 Oct 2024 20:04:26 +0100 Subject: [PATCH 1/4] Enhancements and Alignments in Errors --- documentation/API-design-guidelines.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..cd30bd4c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -777,10 +777,22 @@ In the following, we elaborate on the existing client errors. In particular, we | 503 | `UNAVAILABLE` | Service Unavailable. | Service is not available. Temporary situation usually related to maintenance process in the server side | | 504 | `TIMEOUT` | Request timeout exceeded. | API Server Timeout | -> _NOTE 1: When no login has been performed or no authentication has been assigned, a non-descriptive generic error will always be returned in all cases, a `UNAUTHENTICATED` 401 “Request not authenticated due to missing, invalid, or expired credentials.” is returned, whatever the reason._ +> _NOTE 1: When no login has been performed or no authentication has been assigned, a non-descriptive generic error will always be returned in all cases, an `UNAUTHENTICATED` 401 “Request not authenticated due to missing, invalid, or expired credentials.” is returned, whatever the reason._ > _NOTE 2: A {{SPECIFIC_CODE}}, unless it may have traversal scope (i.e. re-usable among different APIs), SHALL follow this scheme for a specific API: {{API_NAME}}.{{SPECIFIC_CODE}}_ + +**Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following: + +- For event notifications flow, the ones defined in [notification-as-cloud-event.yaml](/artifacts/notification-as-cloud-event.yaml) +- For event subscriptions APIs, the ones defined in [event-subscription-template.yaml](/artifacts/camara-cloudevents/event-subscription-template.yaml) +- For the rest of APIs: + - Error status 401 + - Error status 403 + - Error status 429 TOO_MANY_REQUESTS (For rate limit control) + +NOTE: The rest of Error status defined in section 6.1. will be documented depending on specific considerations within a given WG. + ### 6.2 Error Responses - Device Object This section is focused in the guidelines about error responses around the concept of `device` object. From 971f9edf4d859795290284c931bc63d107956dfe Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 5 Nov 2024 22:35:36 +0100 Subject: [PATCH 2/4] covering_part2 --- documentation/API-design-guidelines.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cd30bd4c..e36b0757 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -793,21 +793,21 @@ In the following, we elaborate on the existing client errors. In particular, we NOTE: The rest of Error status defined in section 6.1. will be documented depending on specific considerations within a given WG. -### 6.2 Error Responses - Device Object +### 6.2 Error Responses - Device Object/Phone Number -This section is focused in the guidelines about error responses around the concept of `device` object. +This section is focused in the guidelines about error responses around the concept of `device` object or `phoneNumber` field. The Following table compiles the guidelines to be adopted: | **Case #** | **Description** | **Error status** | **Error code** | **Message example** | |:----------:|:---------------------------------------------------------------------------|:----------------:|:------------------------------:|:---------------------------------------------------------| | 0 | The request body does not comply with the schema | 400 | INVALID_ARGUMENT | Request body does not comply with the schema. | -| 1 | None of the provided device identifiers is supported by the implementation | 422 | UNSUPPORTED_DEVICE_IDENTIFIERS | phoneNumber is required. | -| 2 | Some identifier cannot be matched to a device | 404 | DEVICE_NOT_FOUND | Device identifier not found. | -| 3 | Device identifiers mismatch | 422 | DEVICE_IDENTIFIERS_MISMATCH | Provided device identifiers are not consistent. | -| 4 | Invalid access token context | 403 | INVALID_TOKEN_CONTEXT | Device identifiers are not consistent with access token. | -| 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. | -| 6 | The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token | 422 | UNIDENTIFIABLE_DEVICE | The device cannot be identified. | +| 1 | None of the provided device identifiers is supported by the implementation | 422 | UNSUPPORTED_IDENTIFIER | The identifier provided is not supported. | +| 2 | Some identifier cannot be matched to a device | 404 | IDENTIFIER_NOT_FOUND | Device identifier not found. | +| 3 | Device identifiers mismatch | 422 | IDENTIFIER_MISMATCH | Provided identifiers are not consistent. | +| 4 | An explicit identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. | +| 5 | Service not applicable for the provided identifier | 422 | SERVICE_NOT_APPLICABLE | The service is not available for the provided identifier. | +| 6 | An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. | From 7fb35711dcbd3c714ac344b8be0ed51d73eb476b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Fri, 29 Nov 2024 14:41:57 +0100 Subject: [PATCH 3/4] Update documentation/API-design-guidelines.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index e36b0757..40a15f19 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -791,7 +791,7 @@ In the following, we elaborate on the existing client errors. In particular, we - Error status 403 - Error status 429 TOO_MANY_REQUESTS (For rate limit control) -NOTE: The rest of Error status defined in section 6.1. will be documented depending on specific considerations within a given WG. +NOTE: The remaining Error statuses defined in section 6.1 will be documented based on specific considerations for the given API. ### 6.2 Error Responses - Device Object/Phone Number From a3728347e9fc655fca5a8099c52c2bdb6195a2f2 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 2 Dec 2024 12:46:50 +0100 Subject: [PATCH 4/4] align_section_6.1 --- artifacts/CAMARA_common.yaml | 2 +- documentation/API-design-guidelines.md | 24 +++++++++++++----------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 9a032d15..60989e69 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -396,7 +396,7 @@ components: code: NOT_FOUND message: The specified resource is not found. GENERIC_404_IDENTIFIER_NOT_FOUND: - description: Device identifier not found + description: Some identifier cannot be matched to a device value: status: 404 code: IDENTIFIER_NOT_FOUND diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 4f169c6a..4ac2f663 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -759,18 +759,20 @@ In the following, we elaborate on the existing client errors. In particular, we | **Error status** | **Error code** | **Message example** | **Scope/description** | |:----------------:|:-----------------------------:|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 401 | `UNAUTHENTICATED` | Request not authenticated due to missing, invalid, or expired credentials. | Request cannot be authenticated | -| 401 | `AUTHENTICATION_REQUIRED` | New authentication is required. | New authentication is needed, authentication is no longer valid | +| 401 | `UNAUTHENTICATED` | Request not authenticated due to missing, invalid, or expired credentials. | Request cannot be authenticated | +| 401 | `AUTHENTICATION_REQUIRED` | New authentication is required. | New authentication is needed, authentication is no longer valid | | 403 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API (e.g QoD session cannot be created for a set of users) | -| 404 | `NOT_FOUND` | The specified resource is not found. | Resource is not found | -| 404 | `DEVICE_NOT_FOUND` | Device identifier not found. | Device identifier not found | -| 404 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific situation to highlight the resource/concept not found (e.g. use in device) | -| 422 | `DEVICE_IDENTIFIERS_MISMATCH` | Provided device identifiers are not consistent. | Inconsistency between device identifiers not pointing to the same device | -| 422 | `DEVICE_NOT_APPLICABLE` | The service is not available for the provided device. | Service is not available for the provided device | -| 422 | `UNIDENTIFIABLE_DEVICE` | The device cannot be identified. | The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token | -| 422 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Any semantic condition associated to business logic, specifically related to a field or data structure | -| 429 | `QUOTA_EXCEEDED` | Either out of resource quota or reaching rate limiting. | Request is rejected due to exceeding a business quota limit | -| 429 | `TOO_MANY_REQUESTS` | Either out of resource quota or reaching rate limiting. | API Server request limit is overpassed | +| 404 | `NOT_FOUND` | The specified resource is not found. | Resource is not found | +| 404 | `IDENTIFIER_NOT_FOUND` | Device identifier not found. | Some identifier cannot be matched to a device | +| 404 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific situation to highlight the resource/concept not found (e.g. use in device) | +| 422 | `UNSUPPORTED_IDENTIFIER` | The identifier provided is not supported. | None of the provided identifiers is supported by the implementation | +| 422 | `IDENTIFIER_MISMATCH` | Provided identifiers are not consistent. | Inconsistency between identifiers not pointing to the same device | +| 422 | `UNNECESSARY_IDENTIFIER` | The device is already identified by the access token. | An explicit identifier is provided when a device or phone number has already been identified from the access token | +| 422 | `SERVICE_NOT_APPLICABLE` | The service is not available for the provided identifier. | Service not applicable for the provided identifier | +| 422 | `MISSING_IDENTIFIER` | The device cannot be identified. | An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token | +| 422 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Any semantic condition associated to business logic, specifically related to a field or data structure | +| 429 | `QUOTA_EXCEEDED` | Either out of resource quota or reaching rate limiting. | Request is rejected due to exceeding a business quota limit | +| 429 | `TOO_MANY_REQUESTS` | Either out of resource quota or reaching rate limiting. | API Server request limit is overpassed | Server Exceptions