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.