Skip to main content

Versioning

info

Versioning Support in HaaS is now enabled by default through the use of the Get Endpoint Meta endpoint

To ensure CDS Future Dated Obligation (FDO) compliance and enable opt-in, customer driven changes to adapter endpoints, the HaaS product implements a flexible versioning system which splits versioning into request, response and optional flag enablement components. This is communicated using the Get Endpoint Meta operation.

Coordination​

Where an Adapter is known, through Get Endpoint Meta, to support multiple Request and Response versions, HaaS will utilise the lowest version required for the feature flags the space has configured. Request data, if applicable, is selected by HaaS and included within the payload (version attribute) aligned with the versions the Adapter has advertised are supported. Response version is selected by HaaS by specifying the x-haas-v header with a version aligned to what the Adapter has advertised is supported.

By way of example the Extended Authentication Attributes feature allows for additional attributes to be requested other than the username within the consent flow. If the Adapter supported V0 and V1 of RequestGetUsernameAttributes then HaaS would send:

  • RequestGetUsernameAttributesV0 if Extended Authentication Attributes feature was disabled or;
  • RequestGetUsernameAttributesV1 if Extended Authentication Attributes feature was enabled.

Discriminator Mapped Schemas​

Versioning of request and response payloads utilises the OpenAPI 3.0 oneOf keyword to specify the possible versions supported by the specification in question.

# #/components/schemas/RequestGetAttributes
oneOf:
- $ref: RequestGetUsernameAttributesV0.yaml
- $ref: RequestGetUsernameAttributesV1.yaml
discriminator:
propertyName: version
mapping:
V0: ./RequestGetUsernameAttributesV0.yaml
V1: ./RequestGetUsernameAttributesV1.yaml

Schema Monomorphisation Tool​

To avoid tooling incompatibilities with OpenAPI 3.0 oneOf support, Biza supports an OpenAPI generation tool that allows a customer to provide a single version of each request/response that they support and generate an OpenAPI schema and supporting Get Endpoint Meta document without oneOf utilised in responses. This removes all ability to support multiple versions with the generated schema, but will allow the customer to continue generating code with older OpenAPI code generation tooling that does not fully support oneOf.

This allows a customer to generate a specification that transforms a oneOf included definition of:

# #/components/schemas/RequestGetAttributes
oneOf:
- $ref: RequestGetUsernameAttributesV0.yaml
- $ref: RequestGetUsernameAttributesV1.yaml
discriminator:
propertyName: version
mapping:
V0: ./RequestGetUsernameAttributesV0.yaml
V1: ./RequestGetUsernameAttributesV1.yaml

Into a single request version such as:

# #/components/schemas/RequestGetAttributes
$ref: RequestGetUsernameAttributesV0.yaml

Wireline Example​

Adapter 2.x Behaviour​

Payload is requested and returned with version attribute and, in this case relates to V1 request and V0 response.

POST /user/attribute HTTP/1.1
x-haas-v: V0
{
"version": "V1",
"username": "test.user",
"email": "test.user@example.com",
"phoneNumber": "+61488111222",
"dateOfBirth": "1980-01-01",
"invoiceRef": "INV1234566",
"nmi": "612344567890"
}
HTTP 200 OK
Content-Length: 1234
{
"version": "V0",
"userId": "b5d1da97-a796-4e8f-9221-cc3cffafb567",
"otpType": "MOBILE",
"emailAddresses": [ ],
"phoneNumbers": [ "+61488111222"]
}
info

The introduction of the 2.x Adapter series checkpoints the separation from the historical binding of the CDR Data Standards to the Data Adapter version.

DATA ADAPTER V0 RETIREMENT

V0 endpoints that have been superseded by an Adapter V1 (e.g., banking payments, energy billing and energy list accounts) will be retired in September 2024 to align with the retirement of CDR versions equivalent to adapter V0 versions.

tip

The Biza to CDS Endpoint Mapping page maps the CDR Data Standards endpoints to Adapter Endpoints, including the applicable obligation dates and request/response versions.

Data Adapter Versioning Principles​

The following principles apply to the data adapter

  • Biza sets data adapter retirement dates when versions are superseded by new adapter endpoint versions and this is typically based around CDR Future Dated Obligations for retirement.
  • Where feasible, a documented downgrade pathway will be provided so that adapters only need to support one endpoint version covering all current CDR obligations.
  • Upgrading versions is usually only necessary due to retirement dates, or to meet new CDR Future Dated Obligations / HaaS Features

Transformation Guidelines​

As the Consumer Data Standards (CDS) body maintains multiple versions of several APIs it is frequently expected that the Data Holder (DH) supports these versions simultaneously. Typically, the DH must provide the response for each version according to the schema defined by the Biza HaaS API. However, there are instances where Biza will perform the mapping and transform the data without requiring the DH to make additional changes or to support multiple versions. The rules and guidelines on how Biza performs the transformation is described on the relevant endpoint page (see links below).

NOTE

The transformation instances listed below represent those currently known to Biza. Please be aware that there may be future scenarios where transforming the data downwards is not feasible.

If the CDS introduces an endpoint that is incompatible with a previous data adapter version, we will still need you to advertise and maintain the old adapter endpoint for incoming requests. If this situation arises, we will ensure you are notified in advance.

Banking​

Energy​