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):

/api/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:

  • removal of a previously supported HTTP resource
  • an HTTP resource no longer responding to a previously supported HTTP verb
  • A new mandatory attribute or element in an input XML or 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 XML or JSON document that is now either optional or not present

The following changes are considered backwards-compatible:

  • addition of new HTTP resources
  • support for additional verbs on existing HTTP resources
  • new optional attributes or elements in an input XML/JSON document
  • previously mandatory attributes or elements in an input XML/JSON document being made optional
  • new attributes or elements introduced in an output XML/JSON document

As these lists indicate, the XML/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 XML/JSON beyond those specified in this document.

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