Analysis of Commonalities 0.5.0-alpha.1 changes

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