Stability & deprecation
What v1 promises, what may change without notice, and how anything is ever taken away.
What `v1` guarantees
While v1 lives, its paths do not move, an error code does not change meaning, an existing condition does not change status, and a field does not change type or nullability. Anything that would break those is a v2, not a v1 release.
Additive — allowed without notice
- A new endpoint.
- A new OPTIONAL query parameter.
- A new field on a response object.
- A new response header.
- A new value on a field documented as open-ended.
- A raised rate-limit budget.
Never, without a new major version
- Removing a field.
- Renaming a field.
- Changing a field’s type or nullability.
- Removing or re-purposing an error `code`.
- Changing an existing status for an existing condition.
- Tightening a limit.
- Making an optional parameter required.
Your side of the promise
error sentence. This is the other half of the promise: a client that rejects a field it does not recognise will break on a change this page calls safe, and a client that parses error will break on a reworded sentence.Deprecation
A deprecated operation or field is marked deprecated: true in the specification, and carries the reason and its replacement in its description. The spec is the announcement channel because it is the one artifact every client already reads — so a code generator surfaces the deprecation without anyone having to have seen a blog post.
The old behaviour keeps working for the announced window. A field is never removed as a surprise.
How a `v2` would arrive
As a SECOND document at a second path, served alongside v1 — not as a rewrite of it. v1 does not stop working the day v2 ships, and deprecating v1 is itself an announcement under the same window.
The info.version in the specification is the API contract’s version, not the app’s release number: its major is the path version, its minor increments on an additive change from the list above, and its patch on a documentation-only correction.
This page is the published commitment. The internal record it is generated from is the API decision record, docs/decisions/public-api-conventions.md §8.