diff --git a/CHANGELOG.md b/CHANGELOG.md index cc6d4e0c..ad19516d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog Commonalities ## Table of Contents +- **[r3.4](#r34)** - **[r3.3](#r33)** - **[r3.2](#r32)** - **[r3.1](#r31)** @@ -15,6 +16,26 @@ - **[v0.2.0](#v020)** - **[v0.1.0 - Initial version](#v010---initial-version)** +# r3.4 +## Release Notes + +This release contains Commonalities version 0.6.1, a patch release from [r3.3](#r33). +* Commonalities approved deliverables in **[documentation](https://github.com/camaraproject/Commonalities/tree/r3.4/documentation)** folder. +* Commonalities approved artifacts in **[artifacts](https://github.com/camaraproject/Commonalities/tree/r3.4/artifacts)** folder. + +**The relevant details of authentication and consent collection are covered by [release 3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases) of Identity and Consent Management Working Group documents.** + +### Fixed +* ErrorInfo schema properties order in template files aligned to [CAMARA API Design Guide](/documentation/CAMARA-API-Design-Guide.md) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/517 +* Fixed typo in [Gherkin Device Errors Template](/artifacts/testing/C01-device-errors.feature) by @PedroDiez in https://github.com/camaraproject/Commonalities/pull/523 +* Fixed link and description of `SubscriptionId` in event-subscription-template.yaml by @rartych in https://github.com/camaraproject/Commonalities/pull/536 +* Changed networkAccessIdentifier and notification server example to use `example.com` by @Kevsy in https://github.com/camaraproject/Commonalities/pull/530 + +### Removed +* Removed "Hashing Passwords" subsection from CAMARA API Design Guide by @AxelNennker in https://github.com/camaraproject/Commonalities/pull/511 + +**Full Changelog**: https://github.com/camaraproject/Commonalities/compare/r3.3...r3.4 + # r3.3 ## Release Notes diff --git a/README.md b/README.md index d862070d..48383d37 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ NOTE: Guidelines for Release Management of API versions, e.g. the API-Readiness- ## Status and released versions -* Version 0.6.0 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.3 tag](https://github.com/camaraproject/Commonalities/tree/r3.3) +* Version 0.6.1 of guidelines and assets for Fall25 meta-release of CAMARA APIs is available with the [r3.4 tag](https://github.com/camaraproject/Commonalities/releases/tag/r3.4) * Previous releases and pre-releases are available in https://github.com/camaraproject/Commonalities/releases For changes see [CHANGELOG.md](https://github.com/camaraproject/Commonalities/blob/main/CHANGELOG.md). diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 557a3ddd..537cbc08 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -5,8 +5,8 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip - x-camara-commonalities: 0.6 + version: wip + x-camara-commonalities: "0.6" paths: {} components: @@ -100,7 +100,7 @@ components: NetworkAccessIdentifier: description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string - example: "123456789@domain.com" + example: "123456789@example.com" DeviceIpv4Addr: type: object @@ -309,8 +309,8 @@ components: 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 } } + code: "{{SPECIFIC_CODE}}" + message: Message for specific code Generic401: description: Unauthorized headers: @@ -373,8 +373,8 @@ components: 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 } } + code: "{{SPECIFIC_CODE}}" + message: Message for specific code Generic404: description: Not found headers: @@ -412,8 +412,8 @@ components: description: Specific situation to highlight the resource/concept not found value: status: 404 - code: { { SPECIFIC_CODE } } - message: { { SPECIFIC_CODE_MESSAGE } } + code: "{{SPECIFIC_CODE}}" + message: Message for specific code Generic405: description: Method Not Allowed headers: @@ -484,6 +484,7 @@ components: - ABORTED - ALREADY_EXISTS - CONFLICT + - INCOMPATIBLE_STATE - "{{SPECIFIC_CODE}}" examples: GENERIC_409_ABORTED: @@ -504,12 +505,18 @@ components: status: 409 code: CONFLICT message: A specified resource duplicate entry found. + GENERIC_409_INCOMPATIBLE_STATE: + description: A resource referenced in the request is in an incompatible state for the requested operation + value: + status: 409 + code: INCOMPATIBLE_STATE + message: A referenced resource is in an incompatible state. 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 } } + code: "{{SPECIFIC_CODE}}" + message: Message for specific code Generic410: description: Gone headers: @@ -636,8 +643,8 @@ components: 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 } } + code: "{{SPECIFIC_CODE}}" + message: Message for specific code Generic429: description: Too Many Requests headers: @@ -795,3 +802,5 @@ components: status: 504 code: TIMEOUT message: Request timeout exceeded. + + diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index ea1d9927..8a48405b 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -13,7 +13,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "0.6" externalDocs: description: Product documentation at CAMARA @@ -552,7 +552,7 @@ components: SubscriptionId: type: string - description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](/documentation/API-design-guidelines.md#122-event-notification). + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, it SHALL be referred to as `subscriptionId` as per the Commonalities Event Notification Model. example: qs15-h556-rt89-1298 CloudEvent: @@ -609,7 +609,7 @@ components: - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 - example: "https://notificationSendServer12.supertelco.com" + example: "https://notificationSendServer12.example.com" DateTime: type: string diff --git a/artifacts/notification-as-cloud-event.yaml b/artifacts/notification-as-cloud-event.yaml index 2aeaee70..f79b6d22 100644 --- a/artifacts/notification-as-cloud-event.yaml +++ b/artifacts/notification-as-cloud-event.yaml @@ -153,7 +153,7 @@ components: - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 - example: "https://notificationSendServer12.supertelco.com" + example: "https://notificationSendServer12.example.com" CloudEvent: description: The notification callback @@ -333,7 +333,7 @@ components: QOS_STATUS_CHANGED_EXAMPLE: value: id: "123e4567-e89b-12d3-a456-426655440000" - source: "https://notificationSendServer12.supertelco.com" + source: "https://notificationSendServer12.example.com" type: "org.camaraproject.quality-on-demand.v0.qos-status-changed" specversion: "1.0" time: "2023-01-17T13:18:23.682Z" diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 19573065..622bcbd7 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -228,7 +228,7 @@ To ensure interoperability, it is crucial to implement error management that str An error representation MUST NOT differ 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 the field causing it, and include it in the message. +- 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 the field causing it, and include it in the message. The format for this field MUST be `SCREAMING_SNAKE_CASE` (e.g. "INVALID_ARGUMENT"). - A detailed description in `message` - in English language in API specification, it can be changed to other languages in implementation if needed. All these aforementioned fields are mandatory in Error Responses. @@ -278,6 +278,8 @@ In the following, we elaborate on the existing client errors. In particular, we | 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 | +| 409 | `INCOMPATIBLE_STATE` | A referenced resource is in an incompatible state. | A resource referenced in the request is in an incompatible state for the requested operation | + | 409 | `{{SPECIFIC_CODE}}` | `{{SPECIFIC_CODE_MESSAGE}}` | Specific conflict situation that is relevant in the context of the API | Service Exceptions @@ -316,10 +318,12 @@ In the following, we elaborate on the existing client errors. In particular, we > _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}}_ +> _NOTE 3: Meaning of {{API_NAME}}.{{SPECIFIC_CODE}}. The double curly brackets '{{..}}' represent a placeholder to be replaced with the real values for the exception. `API_NAME` is the value of [`api-name`](#551-api-name) in `SCREAMING_SNAKE_CASE` format while `SPECIFIC_CODE` represents the value agreed for a given API error case scenario, in `SCREAMING_SNAKE_CASE` format as well (e.g. CARRIER_BILLING.PAYMENT_DENIED)._ + **Mandatory Errors** to be **documented in CAMARA API Spec YAML** are the following: -- For event subscriptions APIs, the ones defined in Event Subscription section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification.md) -- For event notifications flow, the ones defined in Event Notification section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification.md) +- For event subscriptions APIs, the ones defined in Event Subscription section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md) +- For event notifications flow, the ones defined in Event Notification section of [CAMARA API Event Subscription and Notification Guide](/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md) - For the rest of APIs: - Error status 401 - Error status 403 @@ -626,7 +630,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html # CAMARA Commonalities minor version - x.y - x-camara-commonalities: 0.5 + x-camara-commonalities: "0.6" ``` #### 5.3.1. Title @@ -938,10 +942,6 @@ In the API response, provide relevant error message. Usernames, passwords, session tokens, and API keys SHOULD NOT appear in the URL, as this can be captured in web server logs, making them easily exploitable. See section [6.5. POST or GET for transferring sensitive or complex data](#65-post-or-get-for-transferring-sensitive-or-complex-data). -5. **Hashing passwords**. - - Passwords SHOULD never be transmitted in API bodies; however, if it becomes absolutely necessary, they MUST be hashed to protect the system and minimize potential damage in the event of a compromise. Utilizing strong hashing algorithms is crucial for password security. Effective options include Argon2, PBKDF2, bcrypt, and scrypt, which are designed to securely hash passwords and withstand various attack vectors. - For further guidance, please refer to the [OWASP API Security Project](https://owasp.org/www-project-api-security/). This resource offers comprehensive insights and best practices for securing APIs against common vulnerabilities and threats. ### 6.2. Security Definition @@ -1283,3 +1283,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + diff --git a/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md b/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md index 8921e4ef..dea47582 100644 --- a/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md +++ b/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md @@ -508,7 +508,7 @@ curl -X 'POST' \ ```json { "id": 123654, - "source": "https://notificationSendServer12.supertelco.com", + "source": "https://notificationSendServer12.example.com", "type": "org.camaraproject.device-roaming-subscriptions.v1.roaming-status", "specversion": "1.0", "datacontenttype": "application/json", @@ -545,7 +545,7 @@ curl -X 'POST' \ ```json { "id": 123658, - "source": "https://notificationSendServer12.supertelco.com", + "source": "https://notificationSendServer12.example.com", "type": "org.camaraproject.api.device-roaming-subscriptions.v1.subscription-ended", "specversion": "1.0", "datacontenttype": "application/json",