Analysis of Commonalities 0.5.0

Common 'area' data-type added to CAMARA_common.yaml #315

The Area datatype is defined as follows:

https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml#L134-L220

If currently different Area definitions is used: YES

If currently different Area definitions is used: YES

If currently different Area definitions is used: YES

Normalization of error status and code allowed values using enum #316

For event subscription template

#361

Error Responses should be defined as follows:

Error 422 status UNSUPPORTED_DEVICE_IDENTIFIERS changed to UNSUPPORTED_IDENTIFIER

If Error 422 status UNSUPPORTED_DEVICE_IDENTIFIERS is currently used : YES

If Error 422 status UNSUPPORTED_DEVICE_IDENTIFIERS is currently used : YES

If Error status is currently used in implementation logic : YES

Guidelines for subscription and event notification in API Design Guidelines

#313

#356

updated terminationReason in event notification type "subscription-ends"

If TerminationReason was not defined correctly: YES

If TerminationReason was not defined correctly: YES

If TerminationReason was not defined correctly: YES

It is recommended to provide clarification in all subscription APIs featuring subscriptionMaxEvents and initialEvent.

For APIs featuring subscriptionMaxEvents and initialEvent: YES

For APIs featuring subscriptionMaxEvents and initialEvent: YES

Rules for subscriptions data minimization

11.7 Resource access restriction

Potentially YES

Potentially YES

Potentially YES

The sinkCredential must not be present in `POST` and `GET` responses

Potentially YES

Potentially YES

Potentially YES

added clarification on expiresAt attribute for subscription

Potentially YES

Potentially YES

Potentially YES

Updated error codes and changed info.description template for device / phone number identifiers in Appendix A #324

Use new info.description template for when User identification can be from either an access token or explicit identifier

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: potentially YES

Error codes changed:

403 | INVALID_TOKEN_CONTEXT → 422 | UNNECESSARY_IDENTIFIER

422 | UNIDENTIFIABLE_DEVICE → 422 | MISSING_IDENTIFIER

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: potentially YES

Guidelines regarding mandatory error status and alignment of error codes related to identifiers in API Design Guideliness #329 #351

updated in #374

Error codes changed:

404 | DEVICE_NOT_FOUND → 404 | IDENTIFIER_NOT_FOUND

422 | DEVICE_IDENTIFIERS_MISMATCH → 422 | IDENTIFIER_MISMATCH

422 | DEVICE_NOT_APPLICABLE → 422 | SERVICE_NOT_APPLICABLE

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: YES

For APIs using Device object or phoneNumber as identifier: potentially YES

Mandatory Errors to be documented in CAMARA API Spec YAML:

• Error status 401

• Error status 403

For event subscription/notification - see Section 12.1 and 12.2 of API Design Guidelines

• 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.

Potentially YES

Guidelines on the coverage of error codes in API-Testing-Guidelines #343

For test plans:

• All errors explicitly documented in the API spec must be covered by one or more dedicated error scenarios.

• HTTP Statuses which are not explicitly documented in the API specification should not be covered in the test plan.

Common artifacts for testing error scenarios #325

Common artifacts for device and phoneNumber to be used in test definitions

String format/pattern recommendation in #330

If the data type is string it is recommended to use appropriate modifier property `format` and/or `pattern` whenever possible. The OpenAPI Initiative Formats Registry contains the list of formats used in OpenAPI specifications.

Potentially YES

Potentially YES

Potentially YES

ACCESS_TOKEN_EXPIRED termination reason guidance by #364

Changes in API documentation: In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.

Potentially YES

(only subscriptions)

Potentially YES

(only subscriptions)

Updated rules when using POST for sensitive data #358

When the `POST` method is used: the request body itself MUST be a JSON object and MUST be required, even if all properties are optional

Potentially YES

Potentially YES

Potentially YES

String pattern added to x-correlator scheme in #373 #387

pattern: ^[a-zA-Z0-9-]{0,55}$

example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

Changed guidelines on x-camara-commonalities extension field by @rartych in #375

The extension field `x-camara-commonalities` indicates a minor version of CAMARA Commonalities guidelines that given API specification adheres to.

x-camara-commonalities: 0.5

Improved 403 INVALID_TOKEN_CONTEXT scope/description #377

INVALID_TOKEN_CONTEXT - 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.

See also Updates in Appendix A

Updated message field and description for Error 429 by @rartych in #390

`QUOTA_EXCEEDED` | Out of resource quota. | Request is rejected due to exceeding a business quota limit |

`TOO_MANY_REQUESTS` | Rate limit reached. | Access to the API has been temporarily blocked due to rate or spike arrest limits being reached

Added note and changed descriptions for date-time formats #404

Change the descriptions of subscription parameters:

SinkCredential

accessTokenExpiresUtc

startsAt

expiresAt

Sink format corrected and improved description of protocol and sink properties #414 #418

HTTPS should be used for notifications

Removed sinkCredential from Subscription schema in event-subscription-template.yaml in #400

Removed sinkCredential from Subscription schema in event-subscription-template.yaml