Update x-v header to be mandatory for Register APIs

[ACCC-CDR]

Description

Sector agnostic Register APIs were introduced in v1.15 of the consumer data standards. When these new Register API specifications were released, the x-v header was changed from optional to mandatory. However, this resulted in issue #501 being raised as marking the x-v header as mandatory caused compatibility issues with older versions of these APIs.

As a retirement date for the older versions of the Register APIs has now been set (07-04-2023), only a single version of each Register API will be available to participants. As a default of “1” is currently set when an x-v header is not provided, participants will need to include an x-v header on all relevant requests to Register APIs to ensure they receive a response. Therefore, by natural attrition, the x-v header will become mandatory.

Area Affected

All Register APIs with an optional x-v header, namely:

• Get Data Holder Brands
• Get Software Statement Assertion
• Get Data Holder Statuses
• Get Software Products Statuses
• Get Data Recipients Statuses
• Get Data Recipients

Change Proposed

As of the 07-04-2023 obligation date, update the relevant Register API specifications in the consumer data standards to mark the x-v header as mandatory. Also, update the description of the x-v header to be consistent with the description in the Resource API specifications.

DSB Proposed Solution

The current DSB proposal for this issue can be found in this comment

[perlboy]

DP237 which resulted from #501 stated 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 Deprecation and retirement dates for CDR Register superseded endpoint versions needs to be defined #452
3. If an x-v header is not provided in a request to the Register APIs, the minimum supported version will be assigned as the default, maintaining the current behaviour.

This proposal seems to ignore (3) and be a duplicate of #452?

[CDR-API-Stream]

This issue has been discussed a number of times in the MI calls. The DSB does not believe that there is a need to change the position adopted in Decision Proposal 247.

That said, the statement quoted by @perlboy that the absence of the x-v header would result in the minimum supported version being assumed by deafult does need to be addressed as it is ambiguous. The intent was to express that the minimum version support at the time the DP was published would be assumed, not the minimum version supported at the time of invocation.

To address this it is proposed that the description of these fields will be amended to stipulate the specific version to be assumed. If the Register has deprecated this specific version then the assumption will implicitly result in an unsupported version error.

It is expected that, once the Register deprecates v1 of each of the impacted APIs then the standards will be modified to indicate that the x-v header is mandatory. This change will not occur until next year.

[ACCC-CDR]

@CDR-API-Stream could you confirm that references to deprecating made in the above comment should instead be referring to the retirement of these versions as they have been deprecated since 23/12/21?

Additionally, can you confirm that based on the below statement x-v will become mandatory on 7 April 2023 for the following APIs:

• Get Data Holder Brands
• Get Software Statement Assertion
• Get Data Holder Statuses
• Get Software Products Statuses
• Get Data Recipients Statuses
• Get Data Recipients

It is expected that, once the Register deprecates v1 of each of the impacted APIs then the standards will be modified to indicate that the x-v header is mandatory. This change will not occur until next year.

[CDR-API-Stream]

To clarify the questions raised above and in the MI call the proposed position on this issue is:

The description of the x-v header field for each Register end point will remain optional but will be amended to stipulate the specific version to be assumed as default.

It should be noted that, when the Register has decommissioned (ie. no longer supports in production) this specific default version, the x-v becomes mandatory by default as the default value will resolve to an unsupported version, resulting in error. Clients that continue to leave out the x-v header will cease to function.

At a later time, once the default versions are known to be decommissioned (probably next year), the standards will be updated to mark the x-v header as mandatory and the comment about a default value will be removed.

[nils-work]

This change request was incorporated through ConsumerDataStandardsAustralia/standards#272 (comment)