Get Endpoint Meta
The mechanism used to communicate versioning capabilities is via the adapter endpoint with the getEndpointMeta operation identifier (hosted at /meta/endpoints). This allows an implementer to centralise this configuration to a place that does not have to "big bang" uplift all endpoints unless doing so is required to activate a specific feature.
The HaaS Data Adapter versioning system is a deliberate diversion from the Consumer Data Standards approach to versioning using x-v and x-min-v headers for negotiation. The mechanism used by CDS is quite course in nature, fails to deal with request payload versioning, cannot incorporate feature flags (e.g., text filter on listBankingTransactions) and is not developer friendly with respect to the use of OpenAPI discriminator support (i.e. the version is not in the request/response payload itself).
The following dimensions apply to the Get Endpoint Metadata (getEndpointMeta) operation.
| Attribute | Attribute Name | Description |
|---|---|---|
key | Operation ID | Where schema compliant certain operations can be omitted to indicate to the HaaS environment they are not implemented. They can be added at a later stage to be utilised by HaaS during feature enablement. |
responseVersions | Response Versions | The response payloads returned by an operation are individually versioned and this attribute is used to communicate what versions are supported. Multiple versions can be advertised to allow for per endpoint activation while retaining rollback capability. HaaS will request the lowest advertised version that it needs to support the realm configuration in place. |
requestVersions | Request Version | Where there are request bodies, these request are also versioned with the same rules as Response Versions. |
flags | Flags | Flags are per operation capabilities enablers. Multiple flags can be included per operation to enable various functionality, primarily focused on query parameter and header support. |
Response Exampleβ
The following demonstrates an example snippet from the Get Endpoint Metadata operation specifically related to authentication operations:
"auth": {
"loginInit": null,
"loginVerify": null,
"getUsernameAttributes": {
"flags": [
"SUPPORTS_TIER_HEADER",
"SUPPORTS_V0_VERSIONING"
],
"requestVersions": ["V1"],
"responseVersions": ["V0"]
},
"getUserPrincipals": {
"flags": [
"SUPPORTS_TIER_HEADER"
],
"requestVersions": ["V0"],
"responseVersions": ["V0"]
}
}
This snippet communicates that:
getUsernameAttributesandgetUserPrincipalsare supported resulting in Biza Managed authentication being supportedloginInitandloginVerifyare not supported resulting in Double Blinded authentication not being supportedSUPPORTS_TIER_HEADERflag is enabled on both Biza Managed authentication endpoints which will result in the Endpoint Flag being enabled and thex-haas-performance-tierheader being includedSUPPORTS_V0_VERSIONINGflag is enabled ongetUsernameAttributeswhich will result in HaaS sendingx-haas-vheaders and theversionattribute in requestsgetUsernameAttributessupportsV1requests enabling Extended Authentication Attributes to be used- All other requests and responses are specified at
V0withoutSUPPORTS_V0_VERSIONINGresulting in the expectation of unversioned historical Data Adapter 1.x behaviour