API Versioning Strategist

Demo

Click to play with sound.

---
name: API Versioning Strategist
description: Produces an API version scheme (date-pinned header or URI), a breaking-vs-additive change policy, and a published deprecation/sunset timeline with translation shims. Use when removing or renaming a field or endpoint, tightening validation, cutting a "v2", binding a partner integration to a version, or planning how long an old version lives. Do NOT use when designing the resource shape, URLs, status codes, or pagination of a new endpoint — use REST API Design instead; this skill owns only the version scheme and deprecation path layered on top of that contract.
---
# API Versioning Strategist

Pick a version scheme, classify every change as breaking or additive, and ship a deprecation path that never silently breaks a live integration.

## Workflow

1. **Classify the change first.** Decide whether it is breaking or additive before choosing any mechanism.
   - Breaking: removing/renaming a field or endpoint; adding a required request field; tightening validation; changing a field's type or an enum's semantics; changing error codes or status codes clients branch on.
   - Additive (ship freely within the current version): adding optional request fields; adding response fields; adding endpoints; adding optional enum values clients are told to tolerate.
   - Mandate a tolerant-reader contract: clients MUST ignore unknown fields. Document this so additive changes stay non-breaking.
2. **Choose the scheme to match release cadence.**
   - Frequent, granular evolution → date-pinned versions: clients send a version header (a pinned release identifier), the account is bound to a default, and each release is a small documented set of breaking changes. Scales without parallel rewrites.
   - Coarse, infrequent revisions → URI versioning (`/v1/`): simplest and most visible, but biases toward big-bang jumps. Pick only when releases are rare.
   - Avoid letting a "v2" become a years-long parallel fork of "v1".
3. **Translate at the edge, never fork logic.** Keep one current internal model. Apply ordered version-transform shims that up-convert old requests and down-convert responses to a pinned client's contract. Each shim is small, independently testable, and removable when its version sunsets. Forking business logic per version is forbidden.
4. **Pin every integration, never float.** Bind each client to a fixed version at onboarding so it never moves underneath them. Upgrading is an explicit, opt-in action the client takes after reading a changelog — never an automatic float to current.
5. **Deprecate on a published timeline.** Announce a concrete sunset date, not "soon." On responses served from a deprecated version, emit a `Deprecation` header and a `Sunset` header (HTTP-date), and link migration docs. Give meaningful notice (months for public/partner APIs).
6. **Track per-version usage.** Instrument which clients hit which version so you can reach the stragglers before removal and confirm a version is truly idle before deleting its shim.

## Quality bar