Versioning
The API version is part of the URL path, such as/api/v1/.... Within a version we only make backward-compatible changes:
- new endpoints
- new optional request parameters
- new fields in responses
- new values in enums
Deprecating an endpoint
When we retire an endpoint, we:- Announce it in the changelog and on the endpoint’s docs page, and name the replacement.
- Send the
DeprecationandLinkresponse headers on the endpoint from that day. - Set a removal date at least 6 months after the announcement, and send it in the
Sunsetheader. Security fixes may need a shorter period, with at least 30 days’ notice. - Remove the endpoint after the sunset date.
Deprecation and Sunset headers in your client.