Review Register API descriptions

[CDR-API-Stream]

Description

This issue has been raised to track the progress of an item raised in Maintenance Iteration 18 which was unresolved on conclusion of the consultation period. The details below have been taken from the original comment.

The ACCC suggests that two Register endpoint descriptions should be updated to clarify when data holders are expected to begin appearing in responses, and what information is currently available. This is intended to address questions raised by stakeholders.

Intention and Value of Change

We suggest that the API description in the specification be updated to ensure that users of these endpoints understand their behaviour and the differences between them. These clarifications reflect current Register behaviour. Accordingly, we consider that this change is non-breaking change.

Area Affected

Get Data Holder Brands endpoint description Get Data Holder Brands Summary endpoint description

Change Proposed

We suggest that the relevant endpoint descriptions should be updated to specify that:

• Get Data Holder Brands Summary includes all data holder brands for which product reference data is available. For data holders that are active for consumer data sharing, the value disclosed is the public base uri. For brands that are not active for consumer data sharing, the value disclosed is the uri that discloses product data relevant to that brand, as provided by the relevant data holder.

• Get Data Holder Brands includes all data holders that have become active for consumer data sharing and have not been archived.

[perlboy]

This rewording seems to try and talk around the reality that a data holders base uri will, if active in energy, very likely, not contain product reference data. It also doesn't solve for the description of the publicBaseUri that says Base URI for the Data Holder's Consumer Data Standard public endpoints and isn't aligned with the stated intent of the relevant Decision Proposal that said: "where data holder brands can be discovered from the CDR Register and their associated PRD, outage and status endpoints can be derived". From a technical perspective "disclosed is the uri that discloses" isn't an actually technically accurate statement because it is a base uri on which a path is built.

If the desire is to change the description, fine, but it will be confusing and inaccurate.

Can we finally come back to talking about properly splitting these into publicBaseUri and prdBaseUri and properly solve this really simple problem? All this odd business rule behaviour seems like a lot of extra complexity to avoid one additional field. At least then all endpoints would be disclosing the same information consistently and consumers of the API can be better served?

[ProductCloudCDR]

We disagree with the feedback from @perlboy that these changes are related to plan data in energy as the issue with AER endpoints not being exposed at publicBaseUri is a problem for both the brand and brand summary endpoints and the wording will make no difference.

We also don't support the separation of the publicBaseUri as a solution to the situation in energy as we don't think it will be a permanent solution for the future. For example, if Telco is designated and AGL needs to expose Telco plans as well as energy plans then the problem simply comes back. Designation isn't even needed. This could happen simply through adoption of voluntary standards.

That said, we do suggest a change to the wording as there are real situations where a holder appears in brand summary but not brands because they have an exemption. Not all of these are in the energy sector (e.g. Adelaide Bank, Greater Bank, etc). For these holders they have an interimId but not a dataHolderBrandId and we have found this to be confusing for some of the partners we have worked with.

As a result we suggest the following could be an improvement for the brand summary description:

• Get Data Holder Brands Summary includes all data holders that have become active for consumer data sharing and have not been archived plus additional brands that expose publicly available data only, such as product reference data and discovery endpoints. For data holders that are active for consumer data sharing, the dataHolderBrandId field will be populated. For data holders not active for consumer data sharing, the interimId field will be populated. For data holders that were not, but now are, active for consumer data sharing, both ID fields will be present to allow for traceability over time. In addition, for all data holders, a subset of the brand meta data will be exposed that allows for the discovery of publicly available endpoints.

[perlboy]

We disagree with the feedback from @perlboy that these changes are related to plan data in energy as the issue with AER endpoints not being exposed at publicBaseUri is a problem for both the brand and brand summary endpoints and the wording will make no difference.

Ok but if this is the case I'm interested to hear why this is deemed needing clarification for any other reason then a desire to be able to advertise PRD endpoints within the existing schema on one endpoint, divergent from the Standards specified public base uri. It seems to me the only reason/need to provide this clarification is the absence of a separate prdBaseUri and essentially a sleight of hand was performed to allow a split-view outcome that the community is only just being informed about.

We also don't support the separation of the publicBaseUri as a solution to the situation in energy as we don't think it will be a permanent solution for the future. For example, if Telco is designated and AGL needs to expose Telco plans as well as energy plans then the problem simply comes back. Designation isn't even needed. This could happen simply through adoption of voluntary standards.

For what it's worth I would have thought Product Cloud would be supportive of splitting these endpoints because it would allow the specialised delivery of product data without a dependence on owning, at least in part, the CDR delivery component of a Holders implementation. I guess I'm not understanding the underlying business strategy here.

Anyways, back on track, I'm not here to pre-suppose a hypothetical outcome for a sector which has been openly declared as deferred and for which it is unclear if the Register would or even could list voluntarily (nor would they be obligated to). I think the whole notion of "permanent solution for the future" is a falsity and the Register spec development in particular, for example the high iteration count for Get Metrics or lack of clearly needed change, is a demonstration of this.

I'd also make a suggestion, from prior experience, that singling and naming a brand, even for an example, doesn't always do one favours if you ever find yourself in a business development meeting with them! On that note, if a hypothetical company, let's call them Super Energy & Telco Inc (SETI), was selling both types of offering under their single brand (which seems to match your example) then there's a few options regardless:

1. List SETI Energy and SETI Internet to allow clear differentiation. This approach has overlaps in NBL too given the heavy prevalence of white label delivery differentiated by product label and rollups.
2. List two SETI entries, one per industry, to allow for differentiated endpoints. This actually makes sense because while the brand is the same the legal entity may not be (i.e. SETI may issue individual invoices from SETI Internet Pty Ltd and SETI Energy Pty Ltd)

Regardless, it's all future and unknown state. The request here seems to be a need for clarification driven by queries being raised by PRD consumers around "Why doesn't this endpoint work". I can attest that this is a frequent (and predicted) request into energy data holders from sometimes irate developers.

That said, we do suggest a change to the wording as there are real situations where a holder appears in brand summary but not brands because they have an exemption. Not all of these are in the energy sector (e.g. Adelaide Bank, Greater Bank, etc). For these holders they have an interimId but not a dataHolderBrandId and we have found this to be confusing for some of the partners we have worked with.

The whole idea that an identifier can't be consistent between states was never really answered and I think demonstrates an internal system flaw that the Standards should have never altered for.

As a result we suggest the following could be an improvement for the brand summary description: < snip long paragraph of complex if statements >

To me at least, the need to write paragraphs of clarification like this is only highlighting the confusing nature of the schema and is the anti-thesis of providing a "good developer experience" which comes back to my original statement:

If the desire is to change the description, fine, but it will be confusing and inaccurate.

The approach adopted at the moment is akin to split-view DNS and comes with much of the same issues. While this ticket is one about updating some clarification (as i said "fine") it highlights the flaws in the existing register design and implementation. I note that this issue has been raised and apparently brought into the Maintenance Iteration at the 11th hour at the Regulators behest yet the underlying issue, opened by ecosystem participants and broadly supported has been open since December 2022.