api-versioning

Version an API change

API clients are code you do not control, running versions you cannot see. Change compatibly by default: add, do not remove; widen what you accept, do not narrow what you return. When a break is unavoidable, ship a new version beside the old one, announce the deprecation in machine-readable headers, and remove the old version only on a published date.

Steps

1. Classify the change against Google AIP-180 and the Microsoft REST guidelines. Compatible: a new endpoint; a new optional request field whose absence keeps the old behaviour; a new response field; accepting more input. Breaking:
   • removing or renaming a field, endpoint, enum value or query parameter;
   • changing a type, format, unit, or the serialisation of a value;
   • making an optional request field required, or adding a required one;
   • changing a default, a status code, an error code or the error body shape;
   • no longer populating a field that used to be populated;
   • same shape, different meaning (semantic break). A new value in a response enum breaks clients with exhaustive switches unless the contract already says the enum is extensible. When in doubt, it is breaking.
2. Find the consumers. Call search_lore for the versioning scheme and declared consumers, and find_dependents for the declared cross-repo consumers of the contract (an empty result is not proof of safety). Use the Grep tool for in-repo callers, generated clients and contract tests. Record who is affected.
3. Take the compatible path when one exists. Add the new field beside the old and populate both; accept old and new inputs; keep old defaults. Most "we need v2" tickets are an additive change plus a deprecation.
4. If you must break, use the repo's one versioning mechanism (URL major version /v2/, a header, or a dated api-version parameter); never add a second scheme. The versions share one domain implementation with a thin adapter per version at the edge, not a copied handler tree. An unsupported version gets a clear error listing the supported ones, in the repo's envelope (e.g. 400 for a bad api-version value, 404 for an unknown /vN/ prefix).
5. Pin every live version with contract tests (the contract-test skill): the old version's response is asserted unchanged (field names, types, status codes, error body), and the new version's shape is asserted. Update the OpenAPI document for each version (the openapi-contract skill).
6. Deprecate in machine-readable form. On every response from the deprecated version or endpoint: Deprecation: @<unix-seconds> (RFC 9745), Sunset: <HTTP-date> (RFC 8594), and Link: <doc-url>; rel="deprecation". Log each deprecated call with the caller identity so stragglers can be found; add a CHANGELOG entry. When external consumers exist, get the removal date through request_decision; do not invent one.
7. Migrate the in-repo consumers you own in the same epic; a version no internal client uses is untested.
8. Retire only on the date, via the deprecate-and-remove skill: usage confirmed zero, the old version answers 410 Gone with a pointer to the replacement, then the code is deleted.
9. Evidence with the record-evidence skill: the classification and why, the consumer list, both contract tests passing, and a sample response showing the deprecation headers.