Skip to main content

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.

info

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.

AttributeAttribute NameDescription
keyOperation IDWhere 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.
responseVersionsResponse VersionsThe 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.
requestVersionsRequest VersionWhere there are request bodies, these request are also versioned with the same rules as Response Versions.
flagsFlagsFlags 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:

  • getUsernameAttributes and getUserPrincipals are supported resulting in Biza Managed authentication being supported
  • loginInit and loginVerify are not supported resulting in Double Blinded authentication not being supported
  • SUPPORTS_TIER_HEADER flag is enabled on both Biza Managed authentication endpoints which will result in the Endpoint Flag being enabled and the x-haas-performance-tier header being included
  • SUPPORTS_V0_VERSIONING flag is enabled on getUsernameAttributes which will result in HaaS sending x-haas-v headers and the version attribute in requests
  • getUsernameAttributes supports V1 requests enabling Extended Authentication Attributes to be used
  • All other requests and responses are specified at V0 without SUPPORTS_V0_VERSIONING resulting in the expectation of unversioned historical Data Adapter 1.x behaviour

Meta Versioning Negotiation​

The Get Endpoint Metadata operation is itself versioned. In order to allow for the opportunity for customers to "run ahead" of HaaS implementation a special header, specific to this operation, is introduced:

x-haas-max-v : The maximum meta version this HaaS space can support. The adapter MUST return the meta endpoint response version of this version or lower.

Scenarios​

The following diagrams provide a summarisation of engagement patterns with the Get Endpoint Metadata operation.

HaaS and Adapter Aligned​

HaaS greater than Adapter​

HaaS less than Adapter​

Caching​

When enabled, the Get Endpoint Meta operation is polled every 5 minutes for each adapter attached to the HaaS space which ensures that:

  1. The availability of the Get Endpoint Meta will not affect CDR Data Sharing as a cache will be used as a fallback.
  2. Response times of the Get Endpoint Meta will not contribute to the metric collection activities used when the CDR Get Metrics operation is called.
Note

Please be aware that caching is per service in memory and that an error retrieving an endpoint will continue using the old value.

Further, during a deployment or service restart, an unavailable meta endpoint can cause HaaS availability issues because it lacks a cached value upon boot and requires a value for adapter calls.

API Definition​

Loading...


Endpoint Specific Guidance​

Note that the current schema requires sendNotification to be included in the getEndpointMeta response. If using send-notification based notifications (i.e, adapter-based notifications), you must implement this endpoint as documented.

If you are using SendGrid-based notifications, the sendNotification endpoint is not called by HaaS and does not need to be implemented. However, you should still return a schema compliant getEndpointMeta response (e.g., empty flags, request and response versions).