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.