Versioning and deprecation policy

View as Markdown

In short

The version is in the path (/api/v2). Within v2 we only make additive changes, which your code must tolerate. Breaking changes only ever come in a new version, announced at least 12 months before the old one stops. API v1 is frozen and keeps working.

Versions

Version Path Status
v2 /api/v2 Current. Documented here and in the API reference.
v1 /api/v1 Frozen. It keeps working for existing integrations, including the WordPress plugin, and receives security fixes only. No new features.

The version is part of the path, so a request always gets the behaviour of the version it asks for.

Changes we make within v2

These are additive and can happen at any time, without notice. Write your integration so it copes with them:

  • new endpoints;
  • new optional request parameters and body fields;
  • new fields in responses (ignore fields you don't recognise);
  • new error.code values (treat an unknown code like its error.type);
  • new webhook event types (ignore types you didn't subscribe to);
  • new response headers;
  • longer or reworded error.message text (never parse it);
  • changes to the order of fields in a JSON object.

Every change is listed in the changelog.

Breaking changes

A breaking change is anything that could stop a correctly written integration from working, for example:

  • removing or renaming an endpoint, field, parameter or header;
  • changing a field's type, format or meaning;
  • making an optional parameter required, or adding a new required one;
  • changing the default value of a parameter;
  • changing authentication, or which scope an endpoint needs;
  • changing the error type or status of an existing error.

Breaking changes only ever happen in a new version (v3), never inside v2.

Deprecation and notice

When we plan to retire something:

  1. It is marked deprecated in this documentation and in the OpenAPI spec, with what to use instead.
  2. The deprecation is announced in the changelog with the date it will stop working.
  3. It keeps working for at least 12 months from that announcement.

The same applies to a whole version: v2 will keep working for at least 12 months after v3 is released.

There is one exception. If keeping something running would put customers' data at risk, we may change it sooner, with as much notice as the risk allows, and say so in the changelog.

Frequently asked questions

How do I know which version I am calling?

From the path: every v2 endpoint starts /api/v2. The OpenAPI spec also carries the version in info.version.

Will v1 be switched off?

Not without notice under this policy. v1 is frozen rather than deprecated: it keeps working for the integrations that use it. If that changes, the 12-month notice applies to it too.

Building an integration?

Tell us what you are connecting and we will help you plan it, or book a demo to see the API working.