← ClaudeAtlas

api-versioninglisted

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.
tmj-90/gaffer · ★ 1 · AI & Automation · score 70
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