VERSIONING

Major and Minor are the standard two-part versioning scheme.

Semantic Versioning principles are followed 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.