Analysis of Commonalities 0.5.0-alpha.1 changes

Owned by Rafal Artych
Last updated: Dec 12, 2024
4 min read

(DRAFT)

Changelog

Main CHANGELOG points for 0.5.0-alpha.1:

  • Added

    • Common 'area' data-type added to CAMARA_common.yaml by @tlohmar in #315

    • Security and Privacy Considerations for Filtering in API Design Guidelines by @rartych in #331

    • Security scheme added to CAMARA_common.yaml by @rartych in #335

    • VERSION.yaml file added to indicate Commonalities version by @rartych in #339

    • Filtering for boolean guideline and examples in API Design Guidelines by @rartych in #336

    • Guidelines on the coverage of error codes in API-Testing-Guidelines by @jlurien in #343

  • Changed

    • Normalization of error status and code allowed values using enum by @PedroDiez in #316

    • Guidelines for subscription and event notification in API Design Guidelines by @bigludo7 in #313 main changes:

      • updated terminationReason in event notification type "subscription-ends"

      • updated description of sink and sinkCredential attributes for subscription

      • added rules for subscriptions with device identifier attribute

      • added section 11.7 Resource access restriction relevant to subscriptions

      • added clarification on expiresAt attribute for subscription

    • Updated error codes and changed info.description template for device / phone number identifiers in Appendix A in API Design Guideliness by @eric-murray in #324 and #346

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

  • Fixed

    • Clarification on api-name, filenames and servers object by @rartych in #333

    • Removed broken link to DPV document and updated broken links to CAMARA wiki by @rartych in #347

Analysis

This sections presents of main changes that need to be introduced in API definitions and analysis of impact of changes.

Release Management guidelines on breaking and non-breaking changes.

PR

Changes

Required changes in OAS

Breaking change for API Provider implementation

Breaking change for API Client implementation

PR

Changes

Required changes in OAS

Breaking change for API Provider implementation

Breaking change for API Client implementation

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

Error Responses should be defined as follows:

application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - <status> code: enum: - <code1> - <code2>

YES

NO

NO

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

updated terminationReason in event notification type "subscription-ends"

- MAX_EVENTS_REACHED - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED - ACCESS_TOKEN_EXPIRED - SUBSCRIPTION_DELETED

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

NO

Rules for subscriptions data minimization

NO

NO

NO

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

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

  • Error status 429 TOO_MANY_REQUESTS (For rate limit control)

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

Errors not needed to be documented:

  • 405 METHOD_NOT_ALLOWED

  • 406 NOT_ACCEPTABLE

  • 415 UNSUPPORTED_MEDIA_TYPE

  • 5xx errors

YES

NO

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.

NO

(test plans)

NO

NO

Note: The changes listed in Changes column are just indicative - always double check each requirement in API Design Guidelines.

Further changes expected

 

To be added before RC: