Versioning

From time to time we need to make changes to the API. In order to prevent our changes from breaking your client code we will employ the following versioning strategy.

Versioning is achieved by use of request and response headers.

If you don’t specify a version in your request, then you will be using the v1.0 version of the API.

The following response header tells you which versions are available:

• api-supported-versions

The value is a comma-separated list of versions.

To use a new version you have to supply the following header parameter in the request:

• X-VERSION

Set the value to the version that you require.

You should check to see whether use of the new version is advised and what changes (if any) you
need to make to your code in order to use a new version.

Note. At some point it may become necessary to deprecate a version. We will strive to avoid this but sometimes it is unavoidable. We will give you plenty of notice.

Breaking changes

A breaking change is a change that may require you to make changes to your integration. The following are examples of changes we consider to be breaking changes:

• Removal of a parameter, request field or response field
• Addition of a required parameter or request field without default values
• Changes to the intended functionality of an endpoint
• Introduction of additional validation

A non-breaking change is a change that should not require you to make changes to your integration. In most cases, we will communicate non-breaking changes after they have been released.

Please ensure that your application is designed to be able to handle the following types of non-breaking
changes:

• Addition of new endpoints
• Addition of new methods to existing endpoints
• Addition of new fields in the following scenarios:
  • New fields in responses
  • New optional request fields or parameters
  • New required request fields that have default values
• Addition of a new value returned for an existing text field
• Changes to the order of fields returned within a response
• Addition of an optional request header
• Removal of redundant request header
• Changes to the length of data returned within a field
• Changes to the overall response size
• Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.
• Fixes to HTTP response codes and error codes from incorrect code to correct code