Versioning and deprecation
The version in the path, non-breaking changes and the deprecation process.
Developer documentation
The version is in the path
This documentation describes /api/v1. The version is carried only in the path; no version is selected by header or query.
Non-breaking changes
The following can happen within v1 without prior notice. Your client should tolerate them:
- a new endpoint or method,
- a new field in a response (ignore fields you do not recognise),
- a new optional query filter or body field,
- a new value in an enum (treat values you do not recognise as unknown),
- a new event type or a new error code,
- a new response header.
Every change is checked by machine: the published contract in the repository is compared with the new OpenAPI document, and a change that removes a field, a path or an enum value, or adds a new required input, is not published.
Breaking changes
Removing a field, changing its type or meaning, removing an endpoint or adding a new required input is breaking and needs a new version (/api/v2). When a new version is published, v1 keeps working.
Deprecation
- A deprecated endpoint is marked with
deprecated: truein the OpenAPI document and written to the Changelog. - Every response of that endpoint carries the
Deprecation(RFC 9745) andSunset(RFC 8594) headers; when there is one,Link: <...>; rel="deprecation"points to the migration guide. - The
Sunsetdate is at least 12 months after the deprecation is announced. Until then the endpoint works as it does.
We recommend that your client logs the Deprecation header: that way the calls that need migrating show up by themselves.