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
+42 −28
Merged

Enhancements and Alignments in Errors #329

Changes from 3 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
30 changes: 21 additions & 9 deletions documentation/API-design-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -777,25 +777,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 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)
rartych marked this conversation as resolved.
Show resolved Hide resolved
- 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.
PedroDiez marked this conversation as resolved.
Show resolved Hide resolved

### 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_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. |



Expand Down