api-versioninglisted
Install: claude install-skill tmj-90/gaffer
# 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