Introduction
Decision Proposal 192 proposes to decide on the AEMO Exposed Endpoints to Retailers (Holders). Broadly speaking, the Decision Proposal (DP) appears to have an intent of aligning the AEMO exposed endpoints with those exposed by Holders, even going so far as to state:
The retailers will, in effect, be able to operate as a proxy of the data provided by AEMO
In providing feedback regarding these options, Biza.io seeks to consider a number of key components— notably whether the DP:
- Provides enough detail to be suitably assessed
- Achieves the stated goal of minimising implementation costs
- Achieves the goal of data minimisation and privacy maximisation for accesses to AEMO
Further, Biza.io provides recommendations relative to its analysis with respect to improvements to the DP.
References
The following documents were used and are referenced during preparation of this analysis:
Document Name |
Date (Version) |
URL |
Decision Proposal 192 | July 9 2021 (Update 1) | https://github.com/ConsumerDataStandardsAustralia/standards/issues/192 |
Decision Proposal 194 | June 20 2021 (Initial) | https://github.com/ConsumerDataStandardsAustralia/standards/issues/194 |
API Specification
The DP itself seeks to achieve an outcome for defining a set of API endpoints however does not actually define these endpoints in detail. Instead, the DP describes the alterations in long form, resulting in a somewhat challenging process to understand what is actually proposed.
Nonetheless, as interpreted by Biza.io the following endpoints are to be defined:
Name |
Proposed Path |
Proposed HTTP Method |
Summary of alterations for |
Get Service Point | /energy/electricity/servicepoints | POST |
· Changed to POST · Introduce a payload incorporating an array of · Introduce headers and remove others |
Get Service Point Detail | /energy/electricity/servicepoints/{servicePointId} | GET |
· Introduce headers and remove others |
Get Usage For Service Point | /energy/electricity/servicepoints/{servicePointId}/usage | GET |
· Introduce headers and remove others |
Get Usage For Specific Service Points | /energy/electricity/servicepoints/usage | POST |
· Introduce headers and remove others |
Get DER For Service Point | /energy/electricity/servicepoints/{servicePointId}/der | GET |
· Introduce headers and remove others |
Get DER For Specific Service Points | /energy/electricity/servicepoints/der | POST |
· Introduce headers and remove others |
Modifications to underlying Data Standards
In addition, the DP appears to make the following modifications to the underlying standards:
- Do not pass the x-fapi-auth-date header
- Do not pass the x-fapi-customer-ip-address header
- Do not pass the x-cds-client-headers header
- Introduce an x-cds-arrangement header
Note: Biza.io is broadly in favour of removing the x-fapi-auth-date, x-fapi-customer- ip-address and x-cds-client-headers headers entirely from the Data Standards, particularly as the FAPI WG is currently debating the usefulness of any relying party supplied headers. Because of this, Biza.io does not seek to make a recommendation to pass these through.
Ambiguous Modifications or Additions within the Proposal
The following areas require further clarification:
- The x-fapi-interaction-id is specified as “must be propagated” but it is unclear what the behaviour should be if the ADR did not supply it.
- The DP contains a statement with respect to the x-cds-arrangement of:This field must be populated but AEMO will not receive the retailer, or seek to validate the consent associated with, the arrangementThis statement does not appear to be accurate as, by definition, AEMO would be aware of the retailer accessing the API by way of the authentication in use (ie. API key, certificate etc).Further, the stated objective of “tracing and audit” purposes does not appear to be justified as the x-fapi-interaction-id provides this functionality.
- There is some commentary related to the links object however this doesn’t appear to make any specific change to the actual specification, other than stating a received links object should not be replayed.
Identified Issues within the Proposal
- The path namespace between the AEMO Endpoints and the Holder endpoints is polluted. In situations where a Holder may be utilising a service bus or similar, such overlaps may lead to diagnostic confusion or, worse, unintended reflection attack exposure of AEMO endpoints
- The operation name, notably both the stated name and presumably the name within the resultant OpenAPI specification, overlaps. This is likely to contribute to diagnostic confusion.
- The introduction of x-cds-arrangement appears to mandate that an Arrangement Identifier already exists when making calls.Biza.io does not currently understand how a retailer discovery use case could be implemented if a Consumer is unable to convert their NMI to a servicePointId first
Unnecessary Endpoints and Build Minimisation
While the proposal’s intent is to minimise build by mirroring endpoints, the engineering reality is that a Holder, who on ADR facing endpoints will be acting as a server (Holder APIs), will be acting as a client to AEMO (AEMO APIs).
By definition, this means that a client library must be built. Based on DP191 and DP192, the library will be reasonably divergent from any client library built to test a Holder APIs. On this basis, the actual possible build reduction lies in the minimisation of the AEMO APIs while still delivering Holder APIs such that an efficient data transformation can occur.
Consequently the following endpoints in the proposal appear to be unnecessary:
Name |
Reasoning |
Get DER For Service Point |
· This can be achieved by calling Get DER For Specific Service Points with a single |
Get Usage for Service Point |
· This can be achieved by calling Get Usage for Specific Service Point with a single |
Get Service Points
Needs further consideration. |
· This can be achieved by iteratively calling Get Service Point Detail or; · By introducing a Get Specific Service Points in the ADR facing Standards and aligning with this instead. With no current proposal for DP194 available, it is unclear why this has not |
Recommendations
Biza.io makes the following recommendations:
- Redraft the proposal to explicitly describe the AEMO endpoints being delivered. There is a precedent for the disclosure of separated but related endpoints within how the existing Standards describe the Admin APIs, and doing so would aid in client library production for Holders.
- Alter the names, operationIds and paths of the AEMO endpoints to be deliberately separated from the ADR facing endpoints. As AEMO is, in effect, a Data Holder, albeit within a closed loop, there is already a standard specified for this within Extensibility, eg. /cds-au/v1/aem.
- Mandate that the x-fapi-interaction-id provided to AEMO aligns with the generated x-fapi-interaction-id the Holder would respond with if it was absent from an ADR request.
- Remove the introduced x-cds-arrangement header as it does not appear to serve a valid function. Should x-cds-arrangement remain, clarity should be sought as to whether there is a scenario where an Arrangement Identifier is not established (ie. during consent flow) but endpoint data is required.
- Remove the following APIs for AEMO delivery:
a. Get DER For Service Point
b. Get Usage for Service PointThis would represent a 33% reduction in build requirements associated with this proposal. - Consider the introduction of a Get Specific Service Points into the DP194 proposal and instead align this proposal to it. Alternatively, as per Recommendation 1, introduce such an endpoint explicitly in this specification rather than ambiguously redefining the existing Get Service Points as outlined in the Summary of alterations for AEMO endpoints column of the API breakdown table.
- Remove commentary related to links as it is ambiguous. Traditional standards documents would, at most, place this under Implementation Considerations.
About Biza.io
Biza.io are the market leaders in Data Holder solutions to the Consumer Data Right and are the only pure-play CDR vendor in Australia. Founded by the former Engineering Lead of the Data Standards Body (DSB), Biza.io has been involved in the Data Standards setting process since the very beginning and its personnel remain the largest non-government contributors to the consultations. In addition to its participation within the CDR, Biza.io is also a contributing member of the Financial-grade API (FAPI) Working Group, contributors to the FAPI 1.0 information security profile and co-authors of the Grant Management for OAuth 2.0 specification.
About Our Customers
As of July 2021, Biza.io is directly responsible for delivering, or heavily involved in the verification of, one in three of all active Data Holders. Beyond just a contractual engagement Biza.io considers all its customers partners in the journey toward open data. Our customers choose us to not only achieve compliance but to compete then command the consumer data ecosystem.