Design Principles
General Considerationsβ
The following outlines a list of general considerations uncovered during various implementations:
- Null Safety: Implementations must consider a missing field equivalent to having its value set to
nulland should behave the same regardless of behaviour. This aligns with guidance on the Consumer Data Standards. - Unknown Enumeration Values: In alignment with the Consumer Data Standards blank strings are invalid for
enumeration values. If an enumeration value is not available the field must either be omitted or specified
as
null(where applicable, Biza will default toUnspecifiedif the data adapter value isnull). - Specification First: Whilst we have tried our best to ensure our documentation is 100% aligned with the underlying specification, implementers MUST treat the published OpenAPI specifications as the source of truth.
API Design Principlesβ
The design of APIs within Biza is governed by a number of overall principles. Biza is pragmatic in their application rather than being rigid.
- Simplify: The CDS incorporates multiple endpoints that can be collapsed for data collection. For APIs which deliver information for achieving CDS objectives (ostensibly the Data Adapter) the functionality is collapsed where it makes sense to do so.
- Utilise Upstream Structure: Where possible inherit upstream structures. Where it is not possible keep the original "shape" but apply other principles for engineering benefit (e.g., Strongly Typed).
- Strongly Typed: The Data Standards utilise a series of custom Data Types wrapped in
Stringbased OpenAPI data types. Biza API endpoints utilise strongly typed values where it is reasonable to do so. - Multiple Release Compatibility: When changes are introduced to the Biza API definitions, backward compatibility must be maintained for at least 2 releases but should be maintained for as long as possible.
- Global Version: Biza API definitions eschew the complex version negotiation system within the CDR primarily because it is largely unnecessary within an internal environment. Consequently, each API specification is released as a single version covering all the endpoints it defines.
Note
Please note that the Biza API schemas do not necessarily map 1:1 with CDS APIs. However, the Verification Test Suite (VTS) can be used to confirm the responses to the CDR ecosystem from HaaS.