In short#
The major version is in the path: /v<n>/<endpoint>. A change that can break a working client needs a new major version; a deprecated major version stays available for 30 days after the platform approves its deprecation.
What counts as breaking#
People disagree about what "breaking" means, so here is the written definition.
Not breaking: may happen without notice
- a new field in the response
- a new
enumvalue in an optional field - a new header
- a change in field order
- an improvement in latency
- a clearer error message with the same
code
Breaking: needs a new major version
- removing or renaming a field
- changing a field's type
- changing the meaning of an existing value
- tightening validation on an input
- removing an
enumvalue - changing the status code for an existing case
How deprecation works today#
A deprecated major version stays available for 30 days after the platform approves its deprecation. Subscribers are notified when it is approved. After the removal date the version's routes are removed and the gateway answers 404.
At least 90 days' notice, Deprecation and Sunset headers on the old version, and its routes kept in place until the sunset date; the two lists above published as part of the API design guidelines.
Related#
- Create a version and deprecate one: the provider's side.
- Events and notifications