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.codevalues (treat an unknown code like itserror.type); - new webhook event types (ignore types you didn't subscribe to);
- new response headers;
- longer or reworded
error.messagetext (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:
- It is marked deprecated in this documentation and in the OpenAPI spec, with what to use instead.
- The deprecation is announced in the changelog with the date it will stop working.
- 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.