URL versioning
The version is part of the URL. All v1 endpoints are under/v1, and the token endpoint is under
/oauth. A new major version would use a new prefix, such as /v2, and leave /v1 unchanged.
Backward compatibility
Within/v1 we only make additive changes: new endpoints, new optional request fields, and new
response fields. Build your client to ignore response fields it doesn’t know.
An automated check compares every API change with the published contract and blocks breaking changes
to /v1. If we ever make a breaking change on purpose, we announce it in the changelog
with what changed and how to migrate.
Breaking changes include removing an endpoint, removing or renaming a field, narrowing a type, and
making an optional request field required.
Deprecation headers
Before we remove an endpoint, it returns these standard RFC 8594 response headers:
No v1 endpoint is deprecated today. Watch for these headers and migrate before the
Sunset date.