Endpoints and APIs

Introduction

To support the CDR, participants implement REST APIs (Application Programming Interfaces). The end point is the URI used to refer to a resource, such as an API. 

Data Holders are required to implement the Common and Admin APIs and the APIs specific to their sectors. 

Authentication, authorisation and consent

For authentication and authorisation, Data Holders (DHs) and Accredited Data Recipients (ADRs) are required to implement a number of end points based on the OIDC and FAPI R/W standards. The Consumer Data Standards (CDS) lists these end points and provides references to the relevant sections of the upstream standards. See:

• CDS Security Profile, End Points
  • Authorisation End Point
  • JSON Web Key Set End Point
  • Token End Point
  • UserInfo End Point
  • Introspection End Point
  • Token Revocation End Point
  • CDR Arrangement Revocation End Point
  • Pushed Authorisation End Point. See PAR (OAuth 2.0).

Common APIs

Data Holders are required to implement a number of APIs specific to the Consumer Data Standards. The CDS specify the parameters with which the API is called, the response format, and response headers. 

See:

• CDS Common APIs
  
  • Get Customer
  • Get Customer Detail
  • Get Status
  • Get Outages

Admin APIs

• CDS Admin APIs
  • Metadata Update
  • Get Metrics

Metadata Update

Each Data Holder is expected to periodically contact the register and update their cache of all valid ADRs, their status and their metadata.  When the Metadata Update API is invoked by the Register the Data Holder should execute this periodic process immediately, regardless of how recently it was last executed. This API ensures critical changes in the Register, such as revocation or suspension, are propagated as soon as possible. This is a measure to protect consumers.  It is rarely called but must be implemented.

Get Metrics

Data Holders provide performance measures on request by the ACCC. Metrics are covered in NFRs (Non Functional Requirements). See:

• Non-Functional Requirements (NFRs) - performance, accessibility, traffic limits

Banking APIs

For the banking sector, Data Holders are also required to implement specific APIs.

See:

• CDS Banking APIs
  • Get Accounts
  • Get Bulk Balances
  • Get Balances For Specific Accounts
  • Get Account Balance
  • Get Account Detail
  • Get Transactions For Account
  • Get Transaction Detail
  • Get Direct Debits For Account
  • Get Bulk Direct Debits
  • Get Direct Debits For Specific Accounts
  • Get Scheduled Payments for Account
  • Get Scheduled Payments Bulk
  • Get Scheduled Payments For Specific Accounts
  • Get Payees
  • Get Payee Detail
  • Get Products
  • Get Product Detail

Energy APIs

For the Energy sector, Data Holders are also required to implement specific APIs.

See:

• CDS Energy APIs
• Get Generic Plans
• Get Generic Plan Detail
• Get Service Points
• Get Service Point Detail
• Get Usage For Service Point
• Get Bulk Usage
• Get Usage For Specific Service Points
• Get DER For Service Point
• Get Bulk DER
• Get DER For Specific Service Points
• Get Energy Accounts
• Get Energy Account Detail
• Get Agreed Payment Schedule
• Get Concessions
• Get Balance For Energy Account
• Get Bulk Balances for Energy
• Get Balances For Specific Energy Accounts
• Get Invoices For Account
• Get Bulk Invoices
• Get Invoices For Specific Accounts
• Get Billing For Account
• Get Bulk Billing
• Get Billing For Specific Accounts

Response customer context

For all authenticated APIs, the response has the context of the consumer that authenticated with the Data Holder (DH).
The customer context is provided by way of the Access Token that the Accredited Data Recipient ADR sends to the DH in the Authorisation header. This applies to all authenticated APIs.

Customer present and unattended calls

When the customer is present and logged into the ADR, the call is classified as Customer Present. 

When the ADR is calling an API when the customer is not logged in, the call is classified as Customer Not Present, or Unattended. See CDS Non-functional requirements, Definitions.

For a Customer Present API call, the x-fapi-customer-ip-address is provided, in the HTTP headers of the API call. The x-cds-client-headers header should also be provided.

Unattended calls do not provide x-fapi-customer-ip-address or x-cds-client-headers.

Different NFRs (Non-functional requirements) apply for Customer Present and Unattended calls. 

Responsibility for APIs for white-labelled products

When an ADI provides products to its customers through a white-label arrangement with another ADI, the party responsible for providing the CDR product APIs is the original provider of the products.

Subsections

Bulk requests seek information on several accounts in a single request. Special considerations apply when one or more of the multiple accounts in a request are unavailable, or do not have the required consents associated with them.

The Java Artefacts Data Holder server reference implementation is a guide and tutorial for the Java Artefacts. This collection of Java code demonstrates how to implement APIs and send requests to them.