Versioning

API releases are versioned using a two-part versioning scheme: {major version}.{minor version}.

We broadly follow Semantic Versioning principles when versioning the API. The major version number is incremented when a backwards-incompatible change occurs. The URLs used in the API reflect this by incorporating the major version, using the following pattern (relative to the base URL):

📘

URL

/v{major version number}/{operation-specific component}

Minor version numbers are incremented when backwards-compatible changes occur. These do not require a separate URL.

The following changes are considered backwards-incompatible:

  • A previously-supported HTTP resource is removed
  • An HTTP resource no longer responds to a previously-supported HTTP verb
  • A new mandatory attribute or element is added to an input JSON document (this may be either an entirely new mandatory attribute/element, or a previously optional attribute/element that is now mandatory)
  • A previously "always-present" attribute/element in an output JSON document becomes either optional, or is removed

The following changes are considered backwards-compatible:

  • A new HTTP resource is added
  • Support for additional verbs on existing HTTP resources is added
  • There are new optional attributes or elements in an input JSON document
  • Previously-mandatory attributes or elements in an input JSON document are now optional
  • New attributes or elements are introduced in an output JSON document

🚧

Schema

As these lists indicate, the JSON documents produced and consumed by our API are not based on a strict schema. Client implementations should accordingly be flexible and capable of supporting (eg by ignoring) new elements and attributes in the JSON beyond those specified in this document.

❗️

Version Support

We anticipate supporting at least the most recent major release of the API (including the current one) at any given time.