API versioning

In order to keep our APIs updated with the latest functionality we deliver, we use API versioning to separate on major versions and ensure that functionality is unchanged for existing versions when we make improvements to our features.

The API version is specified in the URL path when making requests to us, e.g. /v1/users, /v2/users and so on.

API versions will be maintained according to the below API maintenance policy:

Status

New Features

Technical Support

Bugs

Security Updates

Main version

:white-check-mark:

:white-check-mark:

:white-check-mark:

:white-check-mark:

Legacy

:x:

:white-check-mark:

Only critical bugs

:white-check-mark:

Deprecated

:x:

:x:

:x:

:white-check-mark:

Removed

:x:

:x:

:x:

:x:

In the top-left corner of this page you can select which API version to view, where stable label indicates which is the main version. Lower numbers indicate legacy or deprecated versions, while higher numbers indicate planned future versions.

New major version

A new major version is released when we make a breaking change to the existing functionality, which means that the change is not backwards compatible and changes will be required on your side to support them. The release of a new major version indicates that this is the new main version of our APIs.

Note that this an non-exhaustive list, so there might be other additional reasons for a new major version.

Here are some examples of what a breaking change might be:

  • Deleting a response field
  • Deleting a resource or method
  • Modifying a required query parameter
  • Modifying a resource or method URI
  • Modifying a field name
  • Modifying authorization
  • Decreasing rate-limits

When a new major version is available, all endpoints will be upgraded to this version. For major versions, a migration guide will be made available together with a change log.

Minor and Patch versions

We do not upgrade versions due to minor or patch changes in the API, which we’ve defined as changes that maintain backward compatibility of the API.

Changes that are considered minor include the following, but are not limited to:

  • Adding resources or methods
  • Adding a response field
  • Adding an optional query parameter

Minor and patch versions will be documented in the change log.

Deprecation and removal

The deprecation time is only applicable to major versions of the APIs. Once a new major version of an API is released, any other versions are considered legacy or deprecated, and the newest version is considered the main version. A legacy version of the API will be supported for 12 months after a new major version has been released. The removal of an API version after the deprecation time has ended is 6 months.

We will let you know well in advance of both deprecation and removal of APIs, making sure that you have all the information and time you need to upgrade to the new version.


Did this page help you?