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
- 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.
- 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.
- 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.
- 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).
- 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).
- 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.
- Migrate the in-repo consumers you own in the same epic; a version no internal
client uses is untested.
- 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.
- 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.
Done when
- The change is classified in writing, with the consumer search attached.
- No existing version changed shape, semantics, status codes or error body.
- Each live version has a passing contract test and an accurate OpenAPI entry.
- Deprecated surfaces emit
Deprecation, Sunset and Link headers; the date was
decided, not assumed.
Anti-patterns
- "It's only a rename" shipped in place; changing a default "because it's better".
- Returning
null for a field that used to be populated to "remove" it.
- A
v2 directory that copy-pastes every handler and drifts from v1.
- Removing the old version before usage logs show zero callers.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While classifying the change you learn the versioning scheme, who consumes each version and the deprecation dates already promised. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: api-versioning3description: Use when a ticket must change an API in a way clients might notice — renaming or removing a field, changing a type or status code, altering semantics — and the change must be made compatibly or through an explicit version with a deprecation path, never as a silent break. Invoke for "change the response shape", "rename the field", "we need v2", "deprecate the old endpoint", or when a contract test fails on purpose.4stack: [node, python, go, java, rust, csharp, kotlin, ruby]5area: backend6metadata:7 source: https://skillmd.com/skills/tmj-90/api-versioning8---910# Version an API change1112API clients are code you do not control, running versions you cannot see. Change13compatibly by default: add, do not remove; widen what you accept, do not narrow what you14return. When a break is unavoidable, ship a new version beside the old one, announce the15deprecation in machine-readable headers, and remove the old version only on a16published date.1718## Steps19201. **Classify the change** against Google AIP-180 and the Microsoft REST guidelines.21 Compatible: a new endpoint; a new optional request field whose absence keeps the old22 behaviour; a new response field; accepting more input. Breaking:23 - removing or renaming a field, endpoint, enum value or query parameter;24 - changing a type, format, unit, or the serialisation of a value;25 - making an optional request field required, or adding a required one;26 - changing a default, a status code, an error code or the error body shape;27 - no longer populating a field that used to be populated;28 - same shape, different meaning (semantic break).29 A new value in a response enum breaks clients with exhaustive switches unless the30 contract already says the enum is extensible. When in doubt, it is breaking.312. **Find the consumers.** Call `search_lore` for the versioning scheme and declared32 consumers, and `find_dependents` for the declared cross-repo consumers of the contract33 (an empty result is not proof of safety). Use the Grep tool for in-repo callers,34 generated clients and contract tests. Record who is affected.353. **Take the compatible path when one exists.** Add the new field beside the old and36 populate both; accept old and new inputs; keep old defaults. Most "we need v2"37 tickets are an additive change plus a deprecation.384. **If you must break, use the repo's one versioning mechanism** (URL major version39 `/v2/`, a header, or a dated `api-version` parameter); never add a second scheme.40 The versions share one domain implementation with a thin adapter per version at the41 edge, not a copied handler tree. An unsupported version gets a clear error listing42 the supported ones, in the repo's envelope (e.g. `400` for a bad `api-version`43 value, `404` for an unknown `/vN/` prefix).445. **Pin every live version with contract tests** (the `contract-test` skill): the old45 version's response is asserted unchanged (field names, types, status codes, error46 body), and the new version's shape is asserted. Update the OpenAPI document for each47 version (the `openapi-contract` skill).486. **Deprecate in machine-readable form.** On every response from the deprecated49 version or endpoint: `Deprecation: @<unix-seconds>` (RFC 9745), `Sunset: <HTTP-date>`50 (RFC 8594), and `Link: <doc-url>; rel="deprecation"`. Log each deprecated call with51 the caller identity so stragglers can be found; add a CHANGELOG entry. When external52 consumers exist, get the removal date through `request_decision`; do not invent one.537. **Migrate the in-repo consumers you own** in the same epic; a version no internal54 client uses is untested.558. **Retire only on the date**, via the `deprecate-and-remove` skill: usage confirmed56 zero, the old version answers `410 Gone` with a pointer to the replacement, then the57 code is deleted.589. **Evidence** with the `record-evidence` skill: the classification and why, the59 consumer list, both contract tests passing, and a sample response showing the60 deprecation headers.6162## Done when6364- The change is classified in writing, with the consumer search attached.65- No existing version changed shape, semantics, status codes or error body.66- Each live version has a passing contract test and an accurate OpenAPI entry.67- Deprecated surfaces emit `Deprecation`, `Sunset` and `Link` headers; the date was68 decided, not assumed.6970## Anti-patterns7172- "It's only a rename" shipped in place; changing a default "because it's better".73- Returning `null` for a field that used to be populated to "remove" it.74- A `v2` directory that copy-pastes every handler and drifts from `v1`.75- Removing the old version before usage logs show zero callers.7677## Capture lore7879This skill is one of the places durable, reusable knowledge naturally surfaces:80**While classifying the change you learn the versioning scheme, who consumes each version and the deprecation dates already promised.** That kind of fact is *lore*. Capture it via the **lore-capture81protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):82call the Memory MCP `suggest_lore` once at the close of your work — reusable83conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.