API versioning policy

We aim to ensure you have a smooth experience as we add and enhance the functionality of our APIs. This article outlines what you can expect from our API versioning and lifecycles so that your applications can be built reliably and powerfully.

How we version

We use major versioning (v1, v2, v3, etc.) to record the changes we make to each API independently. We may add features to the existing major version if they are backwards compatible — see the definitions below. These changes may be documented in the changelogs.

Version Support Guarantee

Minimum 1 year

When a new major version is released, the previous version continues to be supported.

Backwards compatible changes

The following changes do not require a new major version and may be introduced at any time:

Endpoints & methods

✓Adding an endpoint

✓Adding a new method

Parameters & properties

✓Adding an optional query parameter or request/response property

Enumerations

✓Adding a value to a list of enumerations

Breaking changes

The following changes are not backwards compatible and will only be introduced in a new major version:

Endpoints & methods

✕Changing the path of an endpoint

✕Deleting a method of an endpoint

✕Deleting an endpoint

Parameters, headers & properties

✕Adding a new required query parameter, header, or request property

✕Changing the default value of a query parameter, header, or request property

✕Changing the default behaviour (filtering, sorting, pagination)

✕Changing the semantics of a value for a parameter, header, or property

✕Deleting a possible value for a query parameter, header, or request property

✕Deleting or renaming a query parameter, header, or property

Enumerations

✕Renaming or removing an enum value

Data types & nullability

✕Changing the data type of a query parameter or property

✕Changing an optional parameter or property to required

✕Changing a required response property to nullable

Response types

✕Adding certain response types for a method

✕Changing or removing a response type for a method

Semantics

✕Changing the semantics of an endpoint

✕Changing the semantics of a parameter, header, or property

✕Changing the semantics of a value for a parameter, header, or property

✕Changing the relationship between resources