Sector Agnostic Register APIs

[ACCC-CDR]

Description

Under version 4 of the Consumer Data Right (CDR) Rules Accredited Data Recipients (ADRs) can freely interact with any Data Holder regardless of sector. As a result, the Register Application and Accreditation Platform (RAAP) is not required and has not implemented functionality to manage which sectors ADRs transact within.

The current Register APIs have {industry} within the URI path, inferring this call filters by industry / sector. Data Recipients will not be accredited for a specific sector / industry so the inclusion of this parameter is redundant (i.e., all ADR’s will return no matter which industry enumerated value is entered) and will create confusion for participants.

For example, when energy is bought into the ecosystem, when a participant calls Get Data Recipients with ‘banking’ as the industry parameter and then calls the API again with the ‘energy’ industry parameter the ADR details in the responses will be identical.

Area Affected

Register APIs will need to be structured to remove {industry} within the URI path. To ensure consistency across the Register APIs and minimise future change management for participants this change is proposed for the Data Recipient and Data Holder URIs which are listed below:

• GetDataRecipients
• GetDataRecipientStatus
• GetSoftwareProductStatus
• GetSoftwareStatementAssertion
• GetDataHolderStatus
• GetDataHolderBrands

Change Proposed

To ensure that the standards align with the current RAAP implementation the following changes are required:

• Reissue APIs without the industry parameter:
  • https:// <register-base-url> / cdr-register / v1 / data-holders / brands

This has the result of the new APIs having unique paths and not clashing with the old. Documentation will be updated to reflect that the new APIs should be targeted for new builds and the old APIs will be maintained until deprecated, we propose 12 months following the outcome.

• Specifically remove the {industry} parameter from the URI path for the following register APIs:
  • GetDataRecipients
  • GetDataRecipientStatus
  • GetSoftwareProductStatus
  • GetSoftwareStatementAssertion
  • GetDataHolderStatus
  • GetDataHolderBrands
• The proposed new endpoints would be as below:
  • GetDataRecipients: /cdr-register/v1/data-recipients
  • GetDataRecipientStatus: /cdr-register/v1/data-recipients/status
  • GetSoftwareProductStatus: /cdr-register/v1/data-recipients/brands/software-products/status
  • GetSoftwareStatementAssertion: /cdr-register/v1/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa
  • GetDataHolderStatus: /cdr-register/v1/data-holders/status
  • GetDataHolderBrands: /cdr-register/v1/data-holders/brands
• Updated GetDataHolderBrands and GetDataHolderStatus APIs to include an optional {industry} path parameter appended to the URI. This would allow for a sector agnostic design whilst retaining the option of filtering requests to specific industries.

[CDR-API-Stream]

This change request is effectively requesting a change to the decision made for CR #424. In that CR the original recommendation for accommodating additional sectors was to remove the industry parameter from the path as requested in this CR. In the final decision incorporated into v1.15.0 of the standards another option was adopted. The rationale for this change in position was posted in the comment here: https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/424#issuecomment-1004487250

The two reasons for the change listed in the proposed CR are:

To ensure that the standards align with the current RAAP implementation the following changes are required

and

This has the result of the new APIs having unique paths and not clashing with the old

We are aware that there are also other arguments to do with how accreditation may change in the future as more sectors are added to the regime and generally how the regime and register evolve.

It is entirely appropriate to reverse a previous decision where there is a good rationale. Being pragmatic, however, the bar for a reversal should not be too low otherwise contentious issues where there is real, and reasonable, differences of opinion will never be closed.

In this case the DSB does not see that differences between the existing position adopted in v1.15.0 and the solution proposed in this change request are substantial. The two solutions are functionally equivalent and both result in the old implementation and the new implementation needing to be retained in production for a period of time.

The argument that the standards should be made to adapt to a solution that has already been built is not relevant. While implementation impact is always taken into account the standards are not required to align to any existing implementation choices made by a participant. In a regime with potentially hundreds of participants this would not be feasible.

Additionally, in choosing the solution that was adopted in v1.15.0 the following was also taken into account:

• Retaining the sector in the paths would have the least impact on existing ADR and DH implementations currently participating in the banking sector. The adopted solution would mean that energy retailers could join the regime without existing participants needing to change their implementations at all.
• The Register APIs have always had sector in the path, as have the resource APIs. Maintaining this pattern would be more consistent both across the standards and with previous decisions and would therefore be more easily understood by participants.

In summary:

• The current solution is functionally equivalent to what is proposed here
• The current solution has less implementation impacts on ADRs and DHs
• Future extension may be required as the needs of the regime evolve but this is equally true for both solution options

We would welcome any addition to the this analysis indicating rationale that we may be missed or incorrectly stated.

[ACCC-CDR]

Our concern with the option that is currently published in v1.15.0 is the introduction of additional maintenance build with no benefit to the API and the potential confusion to new participants entering the regime.

Our goal with the design of the register is to enable additional sectors to onboard easily with minimal change, and to reduce confusion for participants implementing solutions.

The additional build requirement with no added benefit comes about on the following APIs.

• Get Software Statement Assertion (SSA)
• Get Software Products Status
• Get Data Recipients Status
• Get Data Recipients

This would bring the above endpoints in line with similar register APIs that don’t have industry functions (Get OpenId Provider Config and Get JWKS)

In these cases, filtering on industry provides no change to the response from the API. The current standard will mean these APIs need to be versioned and new endpoints made available for each new industry, even though no filtering functionality will be provided.

This also has the possibility to add confusion to participants building out solutions, as providing the capability to filter but then returning the same result is not intuitive to the end user.

Some examples might help here to explain where we see issues with the v1.15.0 register API standards.

Get Software Statement Assertion (SSA) Currently the API path is: /cdr-register/v1/{industry}/data-recipients/brands/{dataRecipientBrandId}/software-products/{softwareProductId}/ssa The description for the industry parameter usage is: The industry the participant is retrieving data for (Banking, etc) Where confusion comes in, the SSA is not bound by an industry in any way. If a participant called that API with any supported value in the industry parameter (all, banking, energy, etc) they would get the exact same SSA. We are leading participants to believe that they need to call a different API when that is not the case.

Get Data Recipients Currently the API path is: /cdr-register/v1/{industry}/data-recipients The description for the industry parameter usage is: The industry the participant is retrieving data for (Banking, etc) As above, the changing of the industry value will cause no change to the response. Data Recipients are not bound to or filterable by industry.

This also holds true for the GetDataRecipientStatus and GetSoftwareProductStatus APIs.

This change proposes that this parameter is removed to ensure simplicity moving forward. This will mean less build for participants as the CDR grows to new industries and also less build for the ACCC to support the register.

While the data holder APIs (GetDataHolderStatus & GetDataHolderBrands) are filterable by industry, to ensure that the register APIs remain consistent the proposal moves the industry filter to the end of the API path and makes it optional.

[CDR-API-Stream]

For reference, this issue has been in discussion during the maintenance iteration 10 session on 16/02/2022

The discussion raised questions on where the future requirements of the Register APIs may progress:

ACCC's proposal to remove the industry path parameter raises the following questions:

• What are the key benefits on such a change to the ecosystem? This CR articulates the benefit to the ACCC Register current implementation but not to other stakeholders/ecosystem?
• What is the change impact to the ecosystem? Lots of participants vs 1 register?
• ADRs are not currently accredited by sector. Is it a good assumption to make that this is a constant? It seems unlikely that as the expansion of sectors continues, there won't be some form of industry specific accreditation requirements
• The register assigns an accreditation number per ADR which has the sector in the naming convention e.g.ADRBNK000001. ACCC response: This is to be removed in the future
• Is there consideration to the future where the Register APIs may need to be customised per sector and therefore the path industry field would be required?
• What would constitute an x-v version change? When a new sector comes onboard and the sector enumeration is updated, this would result in an x-v version increment for APIs that reference this enumeration. This would apply to both models.
• GetDataRecipients doesn't have a natural filter across industries given the absence of a sector field. What are the use cases where a data holder will want a subset of data recipients? The requirements here are unclear and there would be benefit in digging deeper?
• What about other filter types such as updated_since?
• Should we focus on understanding the use cases warranting filtering and the appropriateness of the mechanism derived from these requirements? Further analysis is required to determine appropriateness of changes. Further work required defining requirements, benefits, or the impact to participants (positive or negative).

[perlboy]

It's fundamentally unclear to me what value is being introduced to the ecosystem by collapsing APIs. As discussed in the call keeping the industry path in play keeps optionality regarding backward compatibility.

As a simplified example that seems very relevant, retaining the industry path means that an ADR who only participates in banking could retrieve an SSA containing only banking scopes. This is only an example but clearly illustrates the value of keeping such APIs separate.

[CDR-API-Stream]

@perlboy @ACCC-CDR thank you all for your input on this topic.

Its DSB's position that insufficient benefit would be obtained from this change and future improvements to the Register APIs may be negatively impacted by removing the industry path field in the URLs.

The DSB does not see that a case for change has been made in this collaboration and therefore recommends that this change is not adopted

[CDR-API-Stream]

To summarise:

This issue was raised by the ACCC to ensure that the standards align with the current RAAP implementation. Additionally, this change request also challenges the relevance of the industry parameter within the URI path and the potential confusion to new participants entering the regime.

Feedback from the community was unsupportive of this change. The DSB presented further questions to help elicit the requirements for filtering and versioning strategies for the Register APIs to help quantify the benefit of this change request. No analysis was presented by the ACCC in response to this.

Analysis on the impact of change to participants in the ecosystem was also not presented.

The DSB’s position is unsupportive of changes which require multiple participants to adopt rather than one CDR Register, when all else remains equal.

This issue has raised many questions on the future state of the CDR Register APIs. DP 245 seeks to identify how data recipient accreditation negotiation should be enhanced and anticipates significant discussion on the future state of the CDR Register APIs. Further work on the functionality and usability of these APIs will be conducted through this decision proposal.

Through collaboration with industry and the ACCC, the DSB has concluded that insufficient benefit would be obtained from this change and future improvements to the Register APIs may be negatively impacted by removing the industry path field in the URIs.

Please refer to Decision 237 for further details.