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.

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're backwards compatible. See details on what does and doesn't qualify as backwards compatible below. We may document these changes in the changelogs. When a new major version is released, you can expect that support for the previous major version will continue for a minimum of 1 year.

The following are considered backwards compatible API changes:

• Endpoints and methods
  • Adding an endpoint
  • Adding a new method
• Parameters, headers, and properties
  • Adding an optional query parameter or request/response property
• Enumerations
  • Adding a value to a list of enumerations

The following are not considered backwards compatible API changes:

• Endpoints and methods
  • Changing the path of an endpoint
  • Deleting a method of an endpoint
  • Deleting an endpoint
• Parameters, headers, and 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 of a query parameter, header, or request property, including filtering, sorting and pagination behaviours
  • Changing the semantics of a value for a query parameter, header, or request/response property
  • Deleting a possible value for a query parameter, header, or request property
  • Deleting or renaming a query parameter, header, or request/response property
• Data types, nullability, and required/optional
  • Changing the data type of a query parameter or request/response property
  • Changing an optional query parameter/request property to be required
  • Changing a required response property to be 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 query parameter, header, or request/response property
  • Changing the semantics of a value for a query parameter, header, or request/response property
  • Changing the relationship between resources