search

ConsumerDataStandardsAustralia / standards-maintenance

This repository houses the interactions, consultations and work management to support the maintenance of baselined components of the Consumer Data Right API Standards and Information Security profile.
41 stars 9 forks source link

Register API x-v headers moving to mandatory impacts compatibility with older versions of these APIs #501

Closed CDR-API-Stream closed 2 years ago

CDR-API-Stream commented 2 years ago

Description

This issue has been extracted from issue #465 to simplify tracking.   Issue #424 and #425 introduced new versions to the CDR Register APIs to facilitate the introduction of the Energy sector. These new versions are to be maintained in parallel with current versions so as not to impact Banking implementations.

With the introduction of these new versions, the payload and header definitions were updated to align with the CDS conventions.   These changes were made to satisfy the following requirements which have now been identified as conflicting: 1.     Allow two versions of an endpoint to be available at the same time to avoid impact on the banking sector implementations using the older version of these endpoints 2.     Align the header conventions of these endpoints to the CDS, moving the x-v header to mandatory.   By releasing new versions of APIs with mandatory x-v headers, clients would not be able to integrate with older versions of the API when the x-v header is missing.

Therefore changes must be made to maintain a transitionary period while old and new versions of these APIs remain in effect.  

Area Affected

The following versions of the Register APIs were introduced in Issue #424 and #425 and are affected:

API Name Endpoint Method Version
Get Data Holder Brands /{industry}/data-holders/brands GET V2
Get Software Statement Assertion (SSA) /{industry}/data-recipients/ brands/{dataRecipientBrandId}/ software-products/{softwareProductId}/ssa GET V3
Get Software Products Statuses /{industry}/data-recipients/ brands/software-products/status GET V2
Get Data Recipient Statuses /{industry}/data-recipients/status GET V2
Get Data Recipients /{industry}/data-recipients GET V3
Get Data Holder Statuses /{industry}/data-holders/status GET V1

Change Proposed

The DSB proposes the following:

1.     x-v header requirements for Register APIs move back from mandatory to optional during the transition period. 2.     How x-v headers will move from optional to mandatory can be considered in the future after the retirement of old Register API versions, when all clients are using the same version of the API. Please refer to issue #452 3.     If an x-v header is not provided in a Register API request, the minimum supported version will be assigned as the default, maintaining the current behaviour

CDR-API-Stream commented 2 years ago

The proposed changes were applied to the following API versions:

API Name Endpoint Method Version
Get Data Holder Brands /{industry}/data-holders/brands GET V2
Get Software Statement Assertion (SSA) /{industry}/data-recipients/brands/{dataRecipientBrandId}/ softwareproducts/{softwareProductId}/ssa GET V3
Get Software Products Statuses /{industry}/data-recipients/ brands/softwareproducts/status GET V2
Get Data Recipient Statuses /{industry}/data-recipients/status GET V2
Get Data Recipients /{industry}/data-recipients GET V3
Get Data Holder Statuses /{industry}/data-holders/status GET V1

This change was incorporated into release v1.17.0.

Please refer to Decision 237 for further details.