Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhancements and Alignments in Errors #329

Merged
merged 6 commits into from
Dec 3, 2024
Merged

Enhancements and Alignments in Errors #329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4362de5
Enhancements and Alignments in Errors
PedroDiez Oct 30, 2024
6452b97
Merge branch 'main' of https://github.com/PedroDiez/Commonalities int…
PedroDiez Nov 5, 2024
971f9ed
covering_part2
PedroDiez Nov 5, 2024
7fb3571
Update documentation/API-design-guidelines.md
PedroDiez Nov 29, 2024
9365440
updated_with_comments
PedroDiez Nov 29, 2024
a372834
align_section_6.1
PedroDiez Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions artifacts/CAMARA_common.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -609,13 +609,13 @@ components:
code: IDENTIFIER_MISMATCH
message: Provided identifiers are not consistent.
GENERIC_422_SERVICE_NOT_APPLICABLE:
description: Service is not available for the provided identifier
description: Service not applicable for the provided identifier
value:
status: 422
code: SERVICE_NOT_APPLICABLE
message: The service is not available for the provided identifier.
GENERIC_422_MISSING_IDENTIFIER:
description: The identifier is not included in the request and the identifier information cannot be derived from the 3-legged access token
description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token
value:
status: 422
code: MISSING_IDENTIFIER
Expand All @@ -627,7 +627,7 @@ components:
code: UNSUPPORTED_IDENTIFIER
message: The identifier provided is not supported.
GENERIC_422_UNNECESSARY_IDENTIFIER:
description: An explicit identifier is provided when an API subject has already been identified from the access token
description: An explicit identifier is provided when a device or phone number has already been identified from the access token
value:
status: 422
code: UNNECESSARY_IDENTIFIER
Expand Down
62 changes: 38 additions & 24 deletions documentation/API-design-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

<font size="3"><span style="color: blue"> Server Exceptions </span></font>

Expand All @@ -787,25 +789,37 @@ 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}}_

### 6.2 Error Responses - Device Object

This section is focused in the guidelines about error responses around the concept of `device` object.
**Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following:

- For event subscriptions APIs, the ones defined in [12.1 Subscription](#error-definition-for-resource-based-explicit-subscription)
- For event notifications flow, the ones defined in [12.2 Event notification](#error-definition-for-event-notification)
- For the rest of APIs:
- Error status 401
- Error status 403
- Error status 429 TOO_MANY_REQUESTS (For rate limit control)

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

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_IDENTIFIER | The identifier provided is not supported. |
| 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 | An explicit identifier is provided when a device or phone number has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. |
| 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. |
| 6 | 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 | MISSING_IDENTIFIER | The device cannot be identified. |
| 1 | None of the provided 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 | Inconsistency between identifiers not pointing to the same device | 422 | IDENTIFIER_MISMATCH | Provided identifiers are not consistent. |
| 4 | An explicit identifier is provided when a device or phone number 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 device or phone number identification cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. |



Expand Down Expand Up @@ -1797,10 +1811,10 @@ Managing subscription is a draft feature, and it is not mandatory for now. An AP
Error definition described in this guideline applies for subscriptions.

The Following Error codes must be present:
* for `POST`: 400, 401, 403, 409, 415, 429, 500, 503
* for `GET`: 400, 401, 403, 500, 503
* for `GET .../{subscriptionId}`: 400, 401, 403, 404, 500, 503
* for `DELETE`: 400, 401, 403, 404, 500, 503
* for `POST`: 400, 401, 403, 409, 429
* for `GET`: 400, 401, 403
* for `GET .../{subscriptionId}`: 400, 401, 403, 404
* for `DELETE`: 400, 401, 403, 404

Please see in [Commonalities/artifacts/camara-cloudevents](/artifacts/camara-cloudevents) directory ``event-subscription-template.yaml`` for more information and error examples.

Expand Down