Skip to content

Commit

Permalink
Merge branch 'camaraproject:main' into release-2.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@rartych
rartych authored Jan 24, 2025
2 parents 277468f + ed04c87 commit 738fc7b
Show file tree
Hide file tree
Showing 5 changed files with 30 additions and 30 deletions.
10 changes: 5 additions & 5 deletions artifacts/CAMARA_common.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ components:
description: Correlation id for the different services
schema:
type: string
pattern: ^[a-zA-Z0-9-]{1,55}$
pattern: ^[a-zA-Z0-9-]{0,55}$
parameters:
x-correlator:
name: x-correlator
in: header
description: Correlation id for the different services
schema:
type: string
pattern: ^[a-zA-Z0-9-]{1,55}$
pattern: ^[a-zA-Z0-9-]{0,55}$
example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
schemas:
TimePeriod:
Expand Down Expand Up @@ -666,13 +666,13 @@ components:
value:
status: 429
code: QUOTA_EXCEEDED
message: Either out of resource quota or reaching rate limiting.
message: Out of resource quota.
GENERIC_429_TOO_MANY_REQUESTS:
description: API Server request limit is overpassed
description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
value:
status: 429
code: TOO_MANY_REQUESTS
message: Either out of resource quota or reaching rate limiting.
message: Rate limit reached.
Generic500:
description: Internal Server Error
headers:
Expand Down
3 changes: 3 additions & 0 deletions artifacts/camara-cloudevents/event-subscription-template.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -236,11 +236,14 @@ components:
description: Correlation id for the different services
schema:
type: string
pattern: ^[a-zA-Z0-9-]{0,55}$
example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
pattern: ^[a-zA-Z0-9-]{0,55}$
schemas:
ErrorInfo:
type: object
Expand Down
13 changes: 3 additions & 10 deletions artifacts/testing/C01-device-errors.feature
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
Common error scenarios for POST operations with device as input either in the request
body or implied from the access.

NOTES:
NOTES:
* This is not a complete feature but a collection of scenarios that can be applied with minor
modifications to test plans. Test plans would have to copy and adapt the scenarios as part of
their own feature files, along with other scenarios

* These scenarios assume that other properties not explicitly mentioned in the scenario
are set by default to a valid value. This can be specified in the feature Background.

* {{feature_identifier}} has to be substituted to the value corresponding to the feature file where
these scenarios are included.

Expand All @@ -26,7 +26,6 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
And the response property "$.code" is "INVALID_ARGUMENT"
And the response property "$.message" contains a user friendly text


@{{feature_identifier}}_C01.02_device_identifiers_not_schema_compliant
Scenario Outline: Some device identifier value does not comply with the schema
Given the header "Authorization" is set to a valid access token which does not identify a single device
Expand All @@ -44,7 +43,6 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
| $.device.ipv6Address | /components/schemas/DeviceIpv6Address |
| $.device.networkIdentifier | /components/schemas/NetworkAccessIdentifier |


# This scenario may happen e.g. with 2-legged access tokens, which do not identify a single device.
@{{feature_identifier}}_C01.03_device_not_found
Scenario: Some identifier cannot be matched to a device
Expand All @@ -56,19 +54,16 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
And the response property "$.code" is "IDENTIFIER_NOT_FOUND"
And the response property "$.message" contains a user friendly text


@{{feature_identifier}}_C02.04_unnecessary_device
Scenario: Device not to be included when it can be deduced from the access token
Given the header "Authorization" is set to a valid access token identifying a device

And the request body property "$.device" is set to a valid device
When the HTTP "POST" request is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "UNNECESSARY_IDENTIFIER"
And the response property "$.message" contains a user-friendly text


@{{feature_identifier}}_C01.05_missing_device
Scenario: Device not included and cannot be deduced from the access token
Given the header "Authorization" is set to a valid access token which does not identify a single device
Expand All @@ -79,18 +74,17 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
And the response property "$.code" is "MISSING_IDENTIFIER"
And the response property "$.message" contains a user-friendly text


@{{feature_identifier}}_C01.06_unsupported_device
Scenario: None of the provided device identifiers is supported by the implementation
Given that some types of device identifiers are not supported by the implementation
And the header "Authorization" is set to a valid access token which does not identify a single device
And the request body property "$.device" only includes device identifiers not supported by the implementation
When the HTTP "POST" request is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "UNSUPPORTED_IDENTIFIER"
And the response property "$.message" contains a user-friendly text


# When the service is only offered to certain types of devices or subscriptions, e.g. IoT, B2C, etc.
@{{feature_identifier}}_C01.07_device_not_supported
Scenario: Service not available for the device
Expand All @@ -102,7 +96,6 @@ Feature: CAMARA Common Artifact C01 - Test scenarios for device errors
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user-friendly text


# Several identifiers provided but they do not identify the same device
# This scenario may happen with 2-legged access tokens, which do not identify a device
@{{feature_identifier}}_C01.08_device_identifiers_mismatch
Expand Down
10 changes: 3 additions & 7 deletions artifacts/testing/C02-phoneNumber-errors.feature
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@ Feature: CAMARA Common Artifact C02 - Test scenarios for phoneNumber errors

Common error scenarios for POST operations with phoneNumber as input either in the request
body or implied from the access
NOTES:

NOTES:
* This is not a complete feature but a collection of scenarios that can be applied with minor
modifications to test plans. Test plans would have to copy and adapt the scenarios as part of
their own feature files, along with other scenarios.

* These scenarios assume that other properties not explicitly mentioned in the scenario
are set by default to a valid value. This can be specified in the feature Background.

* {{feature_identifier}} has to be substituted to the value corresponding to the feature file where
these scenarios are included.

Expand All @@ -26,7 +26,6 @@ Feature: CAMARA Common Artifact C02 - Test scenarios for phoneNumber errors
And the response property "$.code" is "INVALID_ARGUMENT"
And the response property "$.message" contains a user friendly text


@{{feature_identifier}}_C02.02_phone_number_not_found
Scenario: Phone number not found
Given the header "Authorization" is set to a valid access token which does not identify a single phone number
Expand All @@ -37,7 +36,6 @@ Feature: CAMARA Common Artifact C02 - Test scenarios for phoneNumber errors
And the response property "$.code" is "IDENTIFIER_NOT_FOUND"
And the response property "$.message" contains a user friendly text


@{{feature_identifier}}_C02.03_unnecessary_phone_number
Scenario: Phone number not to be included when it can be deduced from the access token
Given the header "Authorization" is set to a valid access token identifying a phone number
Expand All @@ -48,7 +46,6 @@ Feature: CAMARA Common Artifact C02 - Test scenarios for phoneNumber errors
And the response property "$.code" is "UNNECESSARY_IDENTIFIER"
And the response property "$.message" contains a user friendly text


@{{feature_identifier}}_C02.04_missing_phone_number
Scenario: Phone number not included and cannot be deducted from the access token
Given the header "Authorization" is set to a valid access token which does not identify a single phone number
Expand All @@ -59,7 +56,6 @@ Feature: CAMARA Common Artifact C02 - Test scenarios for phoneNumber errors
And the response property "$.code" is "MISSING_IDENTIFIER"
And the response property "$.message" contains a user friendly text


# When the service is only offered to certain type of subscriptions, e.g. IoT, , B2C, etc
@{{feature_identifier}}_C02.05_phone_number_not_supported
Scenario: Service not available for the phone number
Expand Down
24 changes: 16 additions & 8 deletions documentation/API-design-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -751,7 +751,7 @@ In the following, we elaborate on the existing client errors. In particular, we
| 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 |
| 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. This error should be used only when the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the Three-Legged Access Token. |
| 409 | `ABORTED` | Concurrency conflict. | Concurrency 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 |
Expand All @@ -773,8 +773,8 @@ In the following, we elaborate on the existing client errors. In particular, we
| 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 |
| 429 | `QUOTA_EXCEEDED` | Out of resource quota. | Request is rejected due to exceeding a business quota limit |
| 429 | `TOO_MANY_REQUESTS` | Rate limit reached. | Access to the API has been temporarily blocked due to rate or spike arrest limits being reached |

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

Expand Down Expand Up @@ -803,9 +803,15 @@ In the following, we elaborate on the existing client errors. In particular, we
- 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.
NOTE:
The documentation of non-mandatory error statuses defined in section 6.1 depends on the specific considerations and design of the given API.
- Error statuses 400, 404, 409, 422, 429: These error statuses should be documented based on the API design and the functionality involved. Subprojects evaluate the relevance and necessity of including these statuses in API specifications.
- Error statuses 405, 406, 410, 412, 415, and 5xx: These error statuses are not documented by default in the API specification. However, they should be included if there is a relevant use case that justifies their documentation.
- Special Consideration for error 501 NOT IMPLEMENTED to indicate optional endpoint:
- The use of optional endpoints is discouraged in order to have aligned implementations
- Only for exceptions where an optional endpoint can not be avoided and defining it in separate, atomic API is not possible - error status 501 should be documented as a valid response


### 6.2 Error Responses - Device Object/Phone Number

Expand Down Expand Up @@ -1046,9 +1052,9 @@ With the aim of standardizing the request observability and traceability process

| Name | Description | Schema | Location | Required by API Consumer | Required in OAS Definition | Example |
|----------------|-----------------------------------------------|----------------------|------------------|--------------------------|----------------------------|----------------------------------------|
| `x-correlator` | Service correlator to make E2E observability | `type: string` `pattern: ^[a-zA-Z0-9-]{1,55}$` | Request / Response | No | Yes | b4333c46-49c0-4f62-80d7-f0ef930f1c46 |
| `x-correlator` | Service correlator to make E2E observability | `type: string` `pattern: ^[a-zA-Z0-9-]{0,55}$` | Request / Response | No | Yes | b4333c46-49c0-4f62-80d7-f0ef930f1c46 |

When the API Consumer includes the "x-correlator" header in the request, the API provider must include it in the response with the same value that was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values.
When the API Consumer includes non-empty "x-correlator" header in the request, the API Provider must include it in the response with the same value that was used in the request. Otherwise, it is optional to include the "x-correlator" header in the response with any valid value. Recommendation is to use UUID for values.


In notification scenarios (i.e., POST request sent towards the listener indicated by `sink` address),
Expand Down Expand Up @@ -2090,7 +2096,9 @@ If an API provider issues Three-Legged Access Tokens for use with the API, the f
Whilst it might be considered harmless to proceed if both identify the same User, returning an error only when the two do not match would allow the API consumer to confirm the identity of the User associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User.
In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the Three-Legged Access Token.
If the API scope DOES NOT allow explicit confirmation as to whether the identifiers match, a `422 UNNECESSARY_IDENTIFIER` error MUST be returned whether the identifiers match or not.
If the API scope DOES allow explicit confirmation as to whether the identifiers match, a `403 INVALID_TOKEN_CONTEXT` error MUST be returned if the identifiers do not match and the mismatch is not indicated using some other mechanism (e.g. as an explicit field in the API response body).
If an API provider issues Two-Legged Access Tokens for use with the API, the following error may occur:
- **Neither a Three-legged Access Token nor an explicit User identifier (device or phone number) are provided by the API consumer.**
Expand Down

0 comments on commit 738fc7b

Please sign in to comment.