| 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
- 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.
- 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".
- 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.
- 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.
- 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).
- 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
- Every change is explicitly classified breaking or additive, with a documented rationale for any new version.
- One internal model; all version differences live in removable edge shims, not branched handlers.
- Each integration is bound to a fixed version; nothing auto-upgrades.
- Every deprecation carries a concrete sunset date plus
Deprecation/Sunset headers and a migration link.
- Per-version usage is measurable before any version is removed.
Do NOT
- Do NOT silently change behavior within a published version — additive only.
- Do NOT cut a new version for an additive change; reserve versions for genuinely breaking ones.
- Do NOT fork business logic per version or sprinkle
if version == ... through handlers.
- Do NOT float clients to the current version automatically or auto-migrate them.
- Do NOT announce deprecations without a concrete date, sunset headers, and a migration guide.
- Do NOT impose this machinery on an internal API with a single deployable consumer — coordinate deploys instead. The full scheme is for public, partner, or independently deployed clients you cannot update in lockstep.
