From e3ca9c9923fff9f7a8f2b0e74d495b02fae84275 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Thu, 23 May 2024 17:43:11 +0200 Subject: [PATCH 01/15] error_model_alignment --- artifacts/CAMARA_common.yaml | 240 +++++++++++++++---------- documentation/API-design-guidelines.md | 130 ++++++++++++-- 2 files changed, 265 insertions(+), 105 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index a0fe5a35..9363da7b 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -7,7 +7,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.4.0 + version: 0.4.0-wip paths: {} components: schemas: @@ -124,27 +124,7 @@ components: example: status: 400 code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param - Conflict: - description: Conflict - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: Request could not be processed due to a conflict - FailedPrecondition: - description: Failed precondition - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. + message: Client specified an invalid argument, request body or query param. OutOfRange: description: Out of Range content: @@ -154,7 +134,7 @@ components: example: status: 400 code: OUT_OF_RANGE - message: Client specified an invalid range + message: Client specified an invalid range. Unauthenticated: description: Not Authenticated content: @@ -164,7 +144,17 @@ components: example: status: 401 code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired + message: Request not authenticated due to missing, invalid, or expired credentials. + AuthenticationRequired: + description: Authentication Required + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. PermissionDenied: description: Permission denied content: @@ -174,7 +164,17 @@ components: example: status: 403 code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform + message: Client does not have sufficient permissions to perform this action. + InvalidTokenContext: + description: Invalid Token Context + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: \`{{field}}\` is not consistent with access token. NotFound: description: Not Found content: @@ -185,6 +185,53 @@ components: status: 404 code: NOT_FOUND message: The specified resource is not found. + DeviceNotFound: + description: Device Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. + NotFoundAndOutOfRange: + description: Out Of Range and Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + OutOfRange: + value: + status: 404 + code: OUT_OF_RANGE + message: Out Of Range. + NotFound: + value: + status: 404 + code: NOT_FOUND + message: Not found. + MethodNotAllowed: + description: Method not allowed + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + NotAcceptable: + description: Not Acceptable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. Aborted: description: Aborted content: @@ -194,7 +241,7 @@ components: example: status: 409 code: ABORTED - message: Request aborted. + message: Concurrency conflict. AlreadyExists: description: Already Exists content: @@ -205,122 +252,133 @@ components: status: 409 code: ALREADY_EXISTS message: The resource that a client tried to create already exists. - TooManyRequests: - description: Too Many Requests + Conflict: + description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 429 - code: TOO_MANY_REQUESTS - message: Either out of resource quota or reaching rate limiting. - Internal: - description: Internal Error + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. + Gone: + description: Gone content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 500 - code: INTERNAL - message: Unknown server error.Typically a server bug. - BadGateway: - description: Bad Gateway + status: 410 + code: GONE + message: Access to the target resource is no longer available. + FailedPrecondition: + description: Failed precondition content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 502 - code: BAD_GATEWAY - message: Couldn't reach an upstream internal service. - Unavailable: - description: Service Unavailable + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + UnsupportedMediaType: + description: Unsupported Media Type content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Timeout: - description: Timeout + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + DeviceIdentifiersMismatch: + description: Device Identifiers mismatch content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 504 - code: TIMEOUT - message: Request timeout exceeded - NotImplemented: - description: Not Implemented + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + DeviceNotApplicable: + description: Device not applicable for the service content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet - AuthenticationRequired: - description: Authentication Required + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + TooManyRequests: + description: Too Many Requests content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required - NotFoundAndOutOfRange: - description: Out Of Range and Not Found + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Internal: + description: Internal Error content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - examples: - OutOfRange: - value: - status: 404 - code: OUT_OF_RANGE - message: Out Of Range - NotFound: - value: - status: 404 - code: NOT_FOUND - message: Not found - MethodNotAllowed: - description: Method not allowed + example: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + DataLoss: + description: Data Loss content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target - NotAcceptable: - description: Not Acceptable + status: 500 + code: DATA_LOSS + message: Unrecoverable data loss or data corruption. + NotImplemented: + description: Not Implemented content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 406 - code: NOT_ACCEPTABLE - message: The server can't produce a response matching the content requested - by the client through Accept-* headers - UnsupportedMediaType: - description: Unsupported Media Type + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + BadGateway: + description: Bad Gateway content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: The server refuses to accept the request because the payload format - is in an unsupported format. + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Unavailable: + description: Service Unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable. + Timeout: + description: Timeout + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7644f5ec..9edb1145 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -30,6 +30,8 @@ This document captures guidelines for the API design in CAMARA project. These gu - [5.1 Versioning Strategy](#51-versioning-strategy) - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) - [6. Error Responses](#6-error-responses) + - [### 6.1 Error Responses - Device Object](#61-error-responses---device-object) + - [### 6.2 Normalization use of error responses](#62-normalization-use-of-error-responses) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) - [8.1 Pagination](#81-pagination) @@ -315,7 +317,7 @@ HTTP status response codes indicate if a request has been completed successfully 4. Client Errors (4XX) 5. Server Errors (5XX) -Status codes are defined in the [RFC 2616](https://tools.ietf.org/html/rfc2616#section-10) 10th section. You can get the updated specifications from [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6.5.1). +Status codes are defined in the [RFC 2616](https://tools.ietf.org/html/rfc2616#section-10) 10th section. You can get the updated specifications from [RFC 9110 Status Codes](https://datatracker.ietf.org/doc/html/rfc9110#section-15). Common errors are captured in the table below. @@ -335,6 +337,7 @@ Common errors are captured in the table below. | 406 | 406 (Not Acceptable) status code indicates that the target resource does not have a current representation that would be acceptable to the user, based on the proactive negotiation header fields received in the request, and the server is unwilling to provide a predetermined representation. It must be reported when there is no response by default, and header fields are reported to carry out the content negotiation (Accept, Accept-Charset, Accept-Encoding, Accept-Language). | | 408 | Status code 408 (Request Timeout) indicates that the server did not receive the complete request message within the expected time.
This code is documented at the API portal level, it should not be documented at the API level.| | 409 | The 409 (Conflict) status code indicates when a request conflicts with the current state of the server. | +| 410 | The 410 (Gone) status code indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent. | 415 | The 415 (Unsupported Media Type) status code indicates that the server cannot accept the format of the request body as indicated by the `Content-Type` or `Content-Encoding` request header. The API specification will state what request body format should be used. | | 429 | The 429 (Too Many Requests) status code indicates that the server is temporarily unable to accept any more requests from the client due to the high number of requests recently sent. A `Retry-After` response header may indicate how long the client should wait before trying again. | | 500 | Status code 500 (Internal Server Error) indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
This code must always be documented. It should be used as a general system error.| @@ -631,7 +634,10 @@ An error representation must not be different from the representation of any res - A field "`status`", which can be identified in the response as a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes. - A unique error "`code`", which can be identified and traced for more details. It must be human readable; therefore, it must not be a numeric code. In turn, to achieve a better location of the error, you can reference the value or field that is causing it, and include it in the message. - A detailed description of "`message`" - + +All these aforementioned fields are mandatory in Error Responses. +`status` and `code` fields have normative nature, so as their use has to be normalize (see [Section 6.2](##62-normalization-use-of-error-responses)). On the other hand, `message` is informative and within this document an example is shown. + A JSON error structure is proposed below: ```json @@ -657,39 +663,135 @@ In the following, we elaborate on the existing client errors. In particular, we | **Error code** | Description | |-----|-----| -|`INVALID_ARGUMENT` | A specified resource duplicate entry found. | -|`CONFLICT` | A specified resource duplicate entry found. | +|`INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | +|`CONFLICT` | A specified resource duplicate entry found. | |`OUT_OF_RANGE`| Client specified an invalid range. | -|`PERMISSION_DENIED`| Client does not have sufficient permissions to perform this action. | -|`ABORTED` | Concurrency conflict.| +|`PERMISSION_DENIED`| Client does not have sufficient permissions to perform this action. | +|`ABORTED` | Concurrency conflict. | |`ALREADY_EXISTS` | The resource that a client tried to create already exists. | Service Exceptions | **Error code** | Description | |-----|-----| -|`UNAUTHENTICATED` | Request not authenticated due to missing, invalid, or expired credentials.| -|`NOT_FOUND`| The specified resource is not found. | +|`UNAUTHENTICATED` | Request not authenticated due to missing, invalid, or expired credentials. | +|`NOT_FOUND`| The specified resource is not found. | |`TOO_MANY_REQUESTS`| Either out of resource quota or reaching rate limiting. | -|`AUTHENTICATION_REQUIRED`| New authentication is required. | +|`AUTHENTICATION_REQUIRED`| New authentication is required. | Server Exceptions | **Error code** | Description | |-----|-----| -|`FAILED_PRECONDITION` | Request cannot be executed in the current system state.| +|`FAILED_PRECONDITION` | Request cannot be executed in the current system state. | |`DATA_LOSS`| Unrecoverable data loss or data corruption. | -|`INTERNAL`| Unknown server error. Typically a server bug.| +|`INTERNAL`| Unknown server error. Typically a server bug. | |`BAD_GATEWAY`| An upstream internal service cannot be reached. | -|`UNAVAILABLE`| Request timeout exceeded. | +|`UNAVAILABLE`| Service Unavailable. | |`TIMEOUT`| Request timeout exceeded. | -|`NOT_IMPLEMENTED`| This functionality is not implemented yet | -|`METHOD_NOT_ALLOWED`| The requested method is not allowed/supported on the target resource. | +|`NOT_IMPLEMENTED`| This functionality is not implemented yet. | +|`METHOD_NOT_ALLOWED`| The requested method is not allowed/supported on the target resource. | |`NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | |`UNSUPPORTED_MEDIA_TYPE` | The server refuses to accept the request because the payload format is in an unsupported format. | +|`GONE` | Access to the target resource is no longer available. | > _NOTE: 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._ +### 6.1 Error Responses - Device Object + +This section is focused in the guidelines about error responses around the concept of `device` object. + +Following table compiles the guidelines to be adopted: + +| Case # | validation_description | status_value | code_value | message_example | +| :---: | :--- | :---: | :---: | :--- | +| 0 | The request body does not comply with the schema | 400 | INVALID_ARGUMENT | device 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. | + +#### Templates + +##### response template + +A response will group all examples for same operation and status code +Schema is common for all errors + +``` +description: | + The examples section includes the list of subcases for this status error code to be implemented. In each example `status` and `code` are normative for the specific error case. `message` may be adjusted or localized by the implementation. +headers: + {{response_headers}} +content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + {{case_1}}: + $ref: ""#/components/examples/{{case_1}}" + {{case_2}}: + $ref: ""#/components/examples/{{case_2}}" +``` + +##### example template + +One case will be needed per row in the table above, following this template: + +``` +components: + examples: + {{case_N}}: + summary: {{validation_description}} + description: {{informative description}} + value: + status: {{status_value}} + code: {{code_value}} + message: {{message_example}} +``` + +### 6.2 Normalization use of error responses + +This section aims to provide a common use of the fields `status` and `code` across CAMARA APIs. + +The following table summarizes this normalization: + +| status | code | scope/applicability | +| :-----: | :-----: | ----- | +| 400 | INVALID_ARGUMENT | Generic Syntax Exception | +| 400 | {{SPECIFIC_CODE}} | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | +| 400 | OUT_OF_RANGE | Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested | +| 401 | UNAUTHENTICATED | Request cannot be authenticated | +| 401 | AUTHENTICATION_REQUIRED | New authentication is needed | +| 403 | PERMISSION_DENIED | OAuth2 token access does not have the required scope or when the user fails operational security | +| 403 | INVALID_TOKEN_CONTEXT | Reflect some inconsistency between information in some field of the API and the related OAuth2 Token | +| 403 | {{SPECIFIC_CODE}} | 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 | Resource is not found | +| 404 | DEVICE_NOT_FOUND | Device identifier not found | +| 404 | {{SPECIFIC_CODE}} | Specific situation to highlight the resource/concept not found (e.g. use in device) | +| 405 | METHOD_NOT_ALLOWED | Invalid HTTP verb used with a given endpoint | +| 406 | NOT_ACCEPTABLE | API Server does not accept the media type (`Accept-*` header) indicated by API client | +| 409 | CONFLICT | Duplication of an existing resource | +| 409 | ABORTED | Concurreny of processes | +| 409 | ALREADY_EXISTS | Trying to create an existing resource | +| 409 | {{SPECIFIC_CODE}} | Specific conflict situation that is relevant in the context of the API (e.g. ) | +| 410 | GONE | Use in notifications flow to allow API Consumer to indicate that its callback is no longer available | +| 412 | PRECONDITION_FAILED | Indication by the API Server that the request cannot be processed in current system state | +| 415 | UNSUPPORTED_MEDIA_TYPE | Payload format of the request is in an unsupported format by the Server. Should not happen | +| 422 | DEVICE_IDENTIFIERS_MISMATCH | Inconsistency between device identifiers not pointing to the same device | +| 422 | DEVICE_NOT_APPLICABLE | Service is not available for the provided device | +| 422 | {{SPECIFIC_CODE}} | Any semantic condition associated to business logic, specifically related to a field or data structure | +| 429 | TOO_MANY_REQUESTS | API Server request limit is overpassed | +| 500 | INTERNAL | Problem in Server side. Regular Server Exception | +| 500 | DATA_LOSS | +| 501 | NOT_IMPLEMENTED | Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations | +| 502 | BAD_GATEWAY | Internal routing problem in the Server side that blocks to manage the service properly | +| 503 | UNAVAILABLE | Service is not available. Temporary situation usually related to maintenance process in the server side | +| 504 | TIMEOUT | API Server Timeout | + +> _NOTE: 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}} + ## 7. Common Data Types From 4611515ce7eedb10c961d14b1ccb3966dcdc447b Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Sat, 1 Jun 2024 11:17:32 +0200 Subject: [PATCH 02/15] unify_model_section_61_clarification_AuthN_Z_procedures_error_format --- documentation/API-design-guidelines.md | 129 +++++++++++-------------- 1 file changed, 55 insertions(+), 74 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 9d57168b..28c2e6d0 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -30,8 +30,8 @@ This document captures guidelines for the API design in CAMARA project. These gu - [5.1 Versioning Strategy](#51-versioning-strategy) - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - - [### 6.1 Error Responses - Device Object](#61-error-responses---device-object) - - [### 6.2 Normalization use of error responses](#62-normalization-use-of-error-responses) + - [### 6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) + - [### 6.2 Error Responses - Device Object](#62-error-responses---device-object) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) - [8.1 Pagination](#81-pagination) @@ -626,6 +626,7 @@ Tho ensure this compatibility, the following must be followed. - Variable order rule: DO NOT rely on the order in which data appears in responses from the JSON service, unless the service explicitly specifies it. - Clients MUST NOT transmit personally identifiable information (PII) parameters in the URL. If necessary, use headers. + ## 6. Error Responses In order to guarantee interoperability, one of the most important points is to carry out error management aimed at strictly complying with the error codes defined in the HTTP protocol. @@ -636,7 +637,7 @@ An error representation must not be different from the representation of any res - A detailed description of "`message`" All these aforementioned fields are mandatory in Error Responses. -`status` and `code` fields have normative nature, so as their use has to be normalize (see [Section 6.2](##62-normalization-use-of-error-responses)). On the other hand, `message` is informative and within this document an example is shown. +`status` and `code` fields have normative nature, so as their use has to be standardized (see [Section 6.1](#61-standardized-use-of-camara-error-responses)). On the other hand, `message` is informative and within this document an example is shown. A JSON error structure is proposed below: @@ -657,47 +658,68 @@ The essential requirements to consider would be: - Customization of the generated error based on the error content returned by the final core service should be contemplated. - Latency should be minimized in its management. -In the following, we elaborate on the existing client errors. In particular, we identify the different error codes and cluster them into separate tables, depending on their nature: i) syntax exceptions, ii) service exceptions, and iii) server errors. +> _NOTE: When standardized AuthN/AuthZ flows are used, please refer to [10.2 Security Implementation](#102-security-implementation) and [11.6 Security Definition](#116-security-definition), the format and content of Error Response for those procedures SHALL follow the guidelines of those standards. + +### 6.1 Standardized use of CAMARA error responses + +This section aims to provide a common use of the fields `status` and `code` across CAMARA APIs. + +In the following, we elaborate on the existing client errors. In particular, we identify the different error codes and cluster them into separate tables, depending on their nature: +- i) syntax exceptions +- ii) service exceptions +- iii) server errors Syntax Exceptions -| **Error code** | Description | -|-----|-----| -|`INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | -|`CONFLICT` | A specified resource duplicate entry found. | -|`OUT_OF_RANGE`| Client specified an invalid range. | -|`PERMISSION_DENIED`| Client does not have sufficient permissions to perform this action. | -|`ABORTED` | Concurrency conflict. | -|`ALREADY_EXISTS` | The resource that a client tried to create already exists. | +| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| :--------------: | :------------: | ----------------------- | ----------------------- | +| 400 | `INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | Generic Syntax Exception | +| 400 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | +| 400 | `OUT_OF_RANGE` | Client specified an invalid range. | Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested | +| 403 | `PERMISSION_DENIED` | Client does not have sufficient permissions to perform this action. | OAuth2 token access does not have the required scope or when the user fails operational security | +| 403 | `INVALID_TOKEN_CONTEXT` | `{{field}}` is not consistent with access token. | Reflect some inconsistency between information in some field of the API and the related OAuth2 Token | +| 409 | `ABORTED` | Concurrency conflict. | Concurreny of processes of the same nature scope | +| 409 | `ALREADY_EXISTS` | The resource that a client tried to create already exists. | Trying to create an existing resource | +| 409 | `CONFLICT` | A specified resource duplicate entry found. | Duplication of an existing resource | +| 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions -| **Error code** | Description | -|-----|-----| -|`UNAUTHENTICATED` | Request not authenticated due to missing, invalid, or expired credentials. | -|`NOT_FOUND`| The specified resource is not found. | -|`TOO_MANY_REQUESTS`| Either out of resource quota or reaching rate limiting. | -|`AUTHENTICATION_REQUIRED`| New authentication is required. | +| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| :--------------: | :------------: | ----------------------- | ----------------------- | +| 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_DESCRIPTION}}` | 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_DESCRIPTION}}` | 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 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | 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 -| **Error code** | Description | -|-----|-----| -|`FAILED_PRECONDITION` | Request cannot be executed in the current system state. | -|`DATA_LOSS`| Unrecoverable data loss or data corruption. | -|`INTERNAL`| Unknown server error. Typically a server bug. | -|`BAD_GATEWAY`| An upstream internal service cannot be reached. | -|`UNAVAILABLE`| Service Unavailable. | -|`TIMEOUT`| Request timeout exceeded. | -|`NOT_IMPLEMENTED`| This functionality is not implemented yet. | -|`METHOD_NOT_ALLOWED`| The requested method is not allowed/supported on the target resource. | -|`NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | -|`UNSUPPORTED_MEDIA_TYPE` | The server refuses to accept the request because the payload format is in an unsupported format. | -|`GONE` | Access to the target resource is no longer available. | +| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| :--------------: | :------------: | ----------------------- | ----------------------- | +| 405 | `METHOD_NOT_ALLOWED` | The requested method is not allowed/supported on the target resource. | Invalid HTTP verb used with a given endpoint | +| 406 | `NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | API Server does not accept the media type (`Accept-*` header) indicated by API client | +| 410 | `GONE` | Access to the target resource is no longer available. | Use in notifications flow to allow API Consumer to indicate that its callback is no longer available | +| 412 | `FAILED_PRECONDITION` | Request cannot be executed in the current system state. | Indication by the API Server that the request cannot be processed in current system state | +| 415 | `UNSUPPORTED_MEDIA_TYPE` | The server refuses to accept the request because the payload format is in an unsupported format. | Payload format of the request is in an unsupported format by the Server. Should not happen | +| 500 | `DATA_LOSS` | Unrecoverable data loss or data corruption. | Some data is lost or corrupted when the server is processing the request so as it cannot manage it properly. It may point to a potential problem at DD.BB. level | +| 500 | `INTERNAL` | Unknown server error. Typically a server bug. | Problem in Server side. Regular Server Exception | +| 501 | `NOT_IMPLEMENTED` | This functionality is not implemented yet. | Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations | +| 502 | `BAD_GATEWAY` | An upstream internal service cannot be reached. | Internal routing problem in the Server side that blocks to manage the service properly | +| 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: 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, a `UNAUTHENTICATED` 401 “Request not authenticated due to missing, invalid, or expired credentials.” is returned, whatever the reason._ -### 6.1 Error Responses - Device Object +> _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. @@ -751,47 +773,6 @@ components: message: {{message_example}} ``` -### 6.2 Normalization use of error responses - -This section aims to provide a common use of the fields `status` and `code` across CAMARA APIs. - -The following table summarizes this normalization: - -| status | code | scope/applicability | -| :-----: | :-----: | ----- | -| 400 | INVALID_ARGUMENT | Generic Syntax Exception | -| 400 | {{SPECIFIC_CODE}} | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | -| 400 | OUT_OF_RANGE | Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested | -| 401 | UNAUTHENTICATED | Request cannot be authenticated | -| 401 | AUTHENTICATION_REQUIRED | New authentication is needed | -| 403 | PERMISSION_DENIED | OAuth2 token access does not have the required scope or when the user fails operational security | -| 403 | INVALID_TOKEN_CONTEXT | Reflect some inconsistency between information in some field of the API and the related OAuth2 Token | -| 403 | {{SPECIFIC_CODE}} | 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 | Resource is not found | -| 404 | DEVICE_NOT_FOUND | Device identifier not found | -| 404 | {{SPECIFIC_CODE}} | Specific situation to highlight the resource/concept not found (e.g. use in device) | -| 405 | METHOD_NOT_ALLOWED | Invalid HTTP verb used with a given endpoint | -| 406 | NOT_ACCEPTABLE | API Server does not accept the media type (`Accept-*` header) indicated by API client | -| 409 | CONFLICT | Duplication of an existing resource | -| 409 | ABORTED | Concurreny of processes | -| 409 | ALREADY_EXISTS | Trying to create an existing resource | -| 409 | {{SPECIFIC_CODE}} | Specific conflict situation that is relevant in the context of the API (e.g. ) | -| 410 | GONE | Use in notifications flow to allow API Consumer to indicate that its callback is no longer available | -| 412 | PRECONDITION_FAILED | Indication by the API Server that the request cannot be processed in current system state | -| 415 | UNSUPPORTED_MEDIA_TYPE | Payload format of the request is in an unsupported format by the Server. Should not happen | -| 422 | DEVICE_IDENTIFIERS_MISMATCH | Inconsistency between device identifiers not pointing to the same device | -| 422 | DEVICE_NOT_APPLICABLE | Service is not available for the provided device | -| 422 | {{SPECIFIC_CODE}} | Any semantic condition associated to business logic, specifically related to a field or data structure | -| 429 | TOO_MANY_REQUESTS | API Server request limit is overpassed | -| 500 | INTERNAL | Problem in Server side. Regular Server Exception | -| 500 | DATA_LOSS | -| 501 | NOT_IMPLEMENTED | Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations | -| 502 | BAD_GATEWAY | Internal routing problem in the Server side that blocks to manage the service properly | -| 503 | UNAVAILABLE | Service is not available. Temporary situation usually related to maintenance process in the server side | -| 504 | TIMEOUT | API Server Timeout | - -> _NOTE: 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}} - ## 7. Common Data Types From 082f5e52ddec8920432fe12d97cbce62e4cb5fb3 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 3 Jun 2024 08:03:10 +0200 Subject: [PATCH 03/15] align_CAMARA_common_yaml_error_responses --- artifacts/CAMARA_common.yaml | 464 +++++++++++++++---------- documentation/API-design-guidelines.md | 18 +- 2 files changed, 288 insertions(+), 194 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 9363da7b..28faa07f 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -10,6 +10,11 @@ info: version: 0.4.0-wip paths: {} components: + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string schemas: TimePeriod: properties: @@ -115,270 +120,359 @@ components: example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 responses: - InvalidArgument: - description: Invalid Argument + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param. - OutOfRange: - description: Out of Range - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range. - Unauthenticated: - description: Not Authenticated - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - AuthenticationRequired: - description: Authentication Required - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required. - PermissionDenied: - description: Permission denied - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action. - InvalidTokenContext: - description: Invalid Token Context - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: INVALID_TOKEN_CONTEXT - message: \`{{field}}\` is not consistent with access token. - NotFound: - description: Not Found + 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. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_{{SPECIFIC_CODE}}: + description: Specific Syntax Exception regarding a field that is relevant in the context of the API + value: + status: 400 + code: {{SPECIFIC_CODE}} + message: {{SPECIFIC_CODE_MESSAGE}} + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: The specified resource is not found. - DeviceNotFound: - description: Device Not Found + 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: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: DEVICE_NOT_FOUND - message: Device identifier not found. - NotFoundAndOutOfRange: - description: Out Of Range and Not Found + 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. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + GENERIC_403_{{SPECIFIC_CODE}}: + description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API + value: + status: 403 + code: {{SPECIFIC_CODE}} + message: {{SPECIFIC_CODE_MESSAGE}} + Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: - OutOfRange: + GENERIC_404_NOT_FOUND: + description: Resource is not found value: status: 404 - code: OUT_OF_RANGE - message: Out Of Range. - NotFound: + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_DEVICE_NOT_FOUND: + description: Device identifier not found value: status: 404 - code: NOT_FOUND - message: Not found. - MethodNotAllowed: - description: Method not allowed + code: DEVICE_NOT_FOUND + message: Device identifier not found. + GENERIC_404_{{SPECIFIC_CODE}}: + description: Specific situation to highlight the resource/concept not found + value: + status: 404 + code: {{SPECIFIC_CODE}} + message: {{SPECIFIC_CODE_MESSAGE}} + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target resource. - NotAcceptable: + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 406 - code: NOT_ACCEPTABLE - message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. - Aborted: - description: Aborted - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ABORTED - message: Concurrency conflict. - AlreadyExists: - description: Already Exists - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: ALREADY_EXISTS - message: The resource that a client tried to create already exists. - Conflict: + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + Generic409: description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: A specified resource duplicate entry found. - Gone: + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + 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. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. + GENERIC_409_{{SPECIFIC_CODE}}: + description: Specific conflict situation that is relevant in the context of the API + value: + status: 409 + code: {{SPECIFIC_CODE}} + message: {{SPECIFIC_CODE_MESSAGE}} + Generic410: description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 410 - code: GONE - message: Access to the target resource is no longer available. - FailedPrecondition: + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. + Generic412: description: Failed precondition + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. - UnsupportedMediaType: + examples: + GENERIC_412_FAILED_PRECONDITION: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + Generic415: description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: The server refuses to accept the request because the payload format is in an unsupported format. - DeviceIdentifiersMismatch: - description: Device Identifiers mismatch - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH - message: Provided device identifiers are not consistent. - DeviceNotApplicable: - description: Device not applicable for the service + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 422 - code: DEVICE_NOT_APPLICABLE - message: The service is not available for the provided device. - TooManyRequests: + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_{{SPECIFIC_CODE}}: + description: Any semantic condition associated to business logic, specifically related to a field or data structure + value: + status: 422 + code: {{SPECIFIC_CODE}} + message: {{SPECIFIC_CODE_MESSAGE}} + Generic429: description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: Either out of resource quota or reaching rate limiting. - Internal: - description: Internal Error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: Unknown server error. Typically a server bug. - DataLoss: - description: Data Loss + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + 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: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: DATA_LOSS - message: Unrecoverable data loss or data corruption. - NotImplemented: + examples: + GENERIC_500_DATA_LOSS: + description: Some data is lost or corrupted when the server is processing the request so as it cannot manage it properly. It may point to a potential problem at DD.BB. level + value: + status: 500 + code: DATA_LOSS + message: Unrecoverable data loss or data corruption. + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic501: description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet. - BadGateway: + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 502 - code: BAD_GATEWAY - message: An upstream internal service cannot be reached. - Unavailable: + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: Service unavailable. - Timeout: - description: Timeout + 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: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: 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. diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 28c2e6d0..2bfc22b4 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -671,37 +671,37 @@ In the following, we elaborate on the existing client errors. In particular, we Syntax Exceptions -| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| **Error status** | **Error code** | **Message** | **scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 400 | `INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | Generic Syntax Exception | -| 400 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | +| 400 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | | 400 | `OUT_OF_RANGE` | Client specified an invalid range. | Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested | | 403 | `PERMISSION_DENIED` | Client does not have sufficient permissions to perform this action. | OAuth2 token access does not have the required scope or when the user fails operational security | | 403 | `INVALID_TOKEN_CONTEXT` | `{{field}}` is not consistent with access token. | Reflect some inconsistency between information in some field of the API and the related OAuth2 Token | -| 409 | `ABORTED` | Concurrency conflict. | Concurreny of processes of the same nature scope | +| 409 | `ABORTED` | Concurrency conflict. | Concurreny of processes of the same nature/scope | | 409 | `ALREADY_EXISTS` | The resource that a client tried to create already exists. | Trying to create an existing resource | | 409 | `CONFLICT` | A specified resource duplicate entry found. | Duplication of an existing resource | -| 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | Specific conflict situation that is relevant in the context of the API | +| 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions -| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| **Error status** | **Error code** | **Message** | **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 | -| 403 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | 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) | +| 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_DESCRIPTION}}` | Specific situation to highlight the resource/concept not found (e.g. use in device) | +| 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 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_DESCRIPTION}}` | Any semantic condition associated to business logic, specifically related to a field or data structure | +| 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 -| **Error status** | **Error code** | **Description/Message** | **scope/applicability** | +| **Error status** | **Error code** | **Message** | **scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 405 | `METHOD_NOT_ALLOWED` | The requested method is not allowed/supported on the target resource. | Invalid HTTP verb used with a given endpoint | | 406 | `NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | API Server does not accept the media type (`Accept-*` header) indicated by API client | From 0e44cee83784b6c68ee10ac29de7d72eb019d69d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:19:04 +0200 Subject: [PATCH 04/15] 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 2bfc22b4..f192f40c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -634,7 +634,7 @@ In order to guarantee interoperability, one of the most important points is to c An error representation must not be different from the representation of any resource. A main error message is defined, with JSON structure with the following fields: - A field "`status`", which can be identified in the response as a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes. - A unique error "`code`", which can be identified and traced for more details. It must be human readable; therefore, it must not be a numeric code. In turn, to achieve a better location of the error, you can reference the value or field that is causing it, and include it in the message. -- A detailed description of "`message`" +- A detailed description in "`message`" - in English language in API specification, it can be changed to other language in implementation if needed. All these aforementioned fields are mandatory in Error Responses. `status` and `code` fields have normative nature, so as their use has to be standardized (see [Section 6.1](#61-standardized-use-of-camara-error-responses)). On the other hand, `message` is informative and within this document an example is shown. From bb9e418ecc918044c4c521a7033fba0766b4d154 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:19:17 +0200 Subject: [PATCH 05/15] 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 f192f40c..cce93213 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -671,7 +671,7 @@ In the following, we elaborate on the existing client errors. In particular, we Syntax Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **Error status** | **Error code** | **Message example** | **Scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 400 | `INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | Generic Syntax Exception | | 400 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | From 6f9c2b57e65353e11ed13c8c626c3da7a2297150 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:19:40 +0200 Subject: [PATCH 06/15] 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 cce93213..f0822936 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -685,7 +685,7 @@ In the following, we elaborate on the existing client errors. In particular, we Service Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **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 | From dc068e5b339bcf1f91cb4fe56ed2c002d7c24534 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:19:48 +0200 Subject: [PATCH 07/15] 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 f0822936..412cfaad 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -701,7 +701,7 @@ In the following, we elaborate on the existing client errors. In particular, we Server Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **Error status** | **Error code** | **Message example** | **Scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 405 | `METHOD_NOT_ALLOWED` | The requested method is not allowed/supported on the target resource. | Invalid HTTP verb used with a given endpoint | | 406 | `NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | API Server does not accept the media type (`Accept-*` header) indicated by API client | From ec93be91a1ee111b7bbcce6d9e35e59304b118bd Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 5 Jun 2024 16:29:44 +0200 Subject: [PATCH 08/15] fix_2nd_review_comments --- documentation/API-design-guidelines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 09d2d34f..7d74bc62 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -636,7 +636,7 @@ In order to guarantee interoperability, one of the most important points is to c An error representation must not be different from the representation of any resource. A main error message is defined, with JSON structure with the following fields: - A field "`status`", which can be identified in the response as a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes. - A unique error "`code`", which can be identified and traced for more details. It must be human readable; therefore, it must not be a numeric code. In turn, to achieve a better location of the error, you can reference the value or field that is causing it, and include it in the message. -- A detailed description of "`message`" +- A detailed description in "`message`" - in English language in API specification, it can be changed to other language in implementation if needed. All these aforementioned fields are mandatory in Error Responses. `status` and `code` fields have normative nature, so as their use has to be standardized (see [Section 6.1](#61-standardized-use-of-camara-error-responses)). On the other hand, `message` is informative and within this document an example is shown. @@ -673,7 +673,7 @@ In the following, we elaborate on the existing client errors. In particular, we Syntax Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **Error status** | **Error code** | **Message example** | **Scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 400 | `INVALID_ARGUMENT` | Client specified an invalid argument, request body or query param. | Generic Syntax Exception | | 400 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific Syntax Exception regarding a field that is relevant in the context of the API (e.g. format of an amount) | @@ -687,7 +687,7 @@ In the following, we elaborate on the existing client errors. In particular, we Service Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **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 | @@ -703,7 +703,7 @@ In the following, we elaborate on the existing client errors. In particular, we Server Exceptions -| **Error status** | **Error code** | **Message** | **scope/description** | +| **Error status** | **Error code** | **Message example** | **Scope/description** | | :--------------: | :------------: | ----------------------- | ----------------------- | | 405 | `METHOD_NOT_ALLOWED` | The requested method is not allowed/supported on the target resource. | Invalid HTTP verb used with a given endpoint | | 406 | `NOT_ACCEPTABLE` | The server cannot produce a response matching the content requested by the client through `Accept-*` headers. | API Server does not accept the media type (`Accept-*` header) indicated by API client | From 36ab9a40312d4646e06e3369c1d9688f702b30e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:35:10 +0200 Subject: [PATCH 09/15] 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 43c6a814..362b86cd 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -727,7 +727,7 @@ This section is focused in the guidelines about error responses around the conce Following table compiles the guidelines to be adopted: -| Case # | validation_description | status_value | code_value | message_example | +| **Case #** | **Description** | **Error status** | **Error code** | **Message example** | | :---: | :--- | :---: | :---: | :--- | | 0 | The request body does not comply with the schema | 400 | INVALID_ARGUMENT | device 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. | From 76dbe7452a563ae54066dc45739d0aef5e4654ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:35:17 +0200 Subject: [PATCH 10/15] 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 362b86cd..3f8b2af2 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -738,7 +738,7 @@ Following table compiles the guidelines to be adopted: #### Templates -##### response template +##### Response template A response will group all examples for same operation and status code Schema is common for all errors From b1e2500c4358d97a275eacb8d8db077204ee1984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:35:23 +0200 Subject: [PATCH 11/15] 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 3f8b2af2..d0fe00e6 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -759,7 +759,7 @@ content: $ref: ""#/components/examples/{{case_2}}" ``` -##### example template +##### Examples template One case will be needed per row in the table above, following this template: From 5fde739555f73865b47be6d01e902d9e1775b54a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:35:32 +0200 Subject: [PATCH 12/15] 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 d0fe00e6..37350819 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -743,7 +743,7 @@ Following table compiles the guidelines to be adopted: A response will group all examples for same operation and status code Schema is common for all errors -``` +```yaml description: | The examples section includes the list of subcases for this status error code to be implemented. In each example `status` and `code` are normative for the specific error case. `message` may be adjusted or localized by the implementation. headers: From 3dc3fc072384b41ced40f76ee0ae6e7b4f597009 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 5 Jun 2024 16:35:38 +0200 Subject: [PATCH 13/15] 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 37350819..144b23d6 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -763,7 +763,7 @@ content: One case will be needed per row in the table above, following this template: -``` +```yaml components: examples: {{case_N}}: From ecb499b476d148a02f97eaf073d093a69fcef0bd Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 5 Jun 2024 16:41:19 +0200 Subject: [PATCH 14/15] align_section_6.2_examples_template --- documentation/API-design-guidelines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 144b23d6..c38910ec 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -767,12 +767,12 @@ One case will be needed per row in the table above, following this template: components: examples: {{case_N}}: - summary: {{validation_description}} + summary: {{Description}} description: {{informative description}} value: - status: {{status_value}} - code: {{code_value}} - message: {{message_example}} + status: {{Error status}} + code: {{Error code}} + message: {{Message example}} ``` From e25c87dc9a91054621e8ac4f1c0f4ddeecb4807b Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 11 Jun 2024 10:58:29 +0200 Subject: [PATCH 15/15] remove_DATA_LOSS_error_code --- artifacts/CAMARA_common.yaml | 6 ------ documentation/API-design-guidelines.md | 1 - 2 files changed, 7 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 88a426ae..f18ebc33 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -407,12 +407,6 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - GENERIC_500_DATA_LOSS: - description: Some data is lost or corrupted when the server is processing the request so as it cannot manage it properly. It may point to a potential problem at DD.BB. level - value: - status: 500 - code: DATA_LOSS - message: Unrecoverable data loss or data corruption. GENERIC_500_INTERNAL: description: Problem in Server side. Regular Server Exception value: diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 23959fe5..e47009a7 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -710,7 +710,6 @@ In the following, we elaborate on the existing client errors. In particular, we | 410 | `GONE` | Access to the target resource is no longer available. | Use in notifications flow to allow API Consumer to indicate that its callback is no longer available | | 412 | `FAILED_PRECONDITION` | Request cannot be executed in the current system state. | Indication by the API Server that the request cannot be processed in current system state | | 415 | `UNSUPPORTED_MEDIA_TYPE` | The server refuses to accept the request because the payload format is in an unsupported format. | Payload format of the request is in an unsupported format by the Server. Should not happen | -| 500 | `DATA_LOSS` | Unrecoverable data loss or data corruption. | Some data is lost or corrupted when the server is processing the request so as it cannot manage it properly. It may point to a potential problem at DD.BB. level | | 500 | `INTERNAL` | Unknown server error. Typically a server bug. | Problem in Server side. Regular Server Exception | | 501 | `NOT_IMPLEMENTED` | This functionality is not implemented yet. | Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations | | 502 | `BAD_GATEWAY` | An upstream internal service cannot be reached. | Internal routing problem in the Server side that blocks to manage the service properly |