Skip to main content

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 null and 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 to Unspecified if the data adapter value is null).
  • 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 String based 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.