Versions Compared

Old Version 2

changes.mady.by.user Rafal Artych

Saved on

compared with

New Version 3

changes.mady.by.user Rafal Artych

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Changelog

Release PR ready for final review, main CHANGELOG points:

  • 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

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

  • 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

Breaking change for 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:

Code Block
languageyaml
  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"

Code Block
    - 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: YES

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: YES