Api versioning strategist

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 - ideally 1-5 per release, never dozens. Scales without parallel rewrites.
   • Coarse, infrequent revisions → URI versioning (/v1/): simplest and most visible, but biases toward big-bang jumps. Pick only when breaking releases happen roughly once a year or less.
   • 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 a minimum of 6 months' notice for partner APIs and 12 months for broad public APIs; internal APIs with known consumers can move in 30-90 days.
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. A practical removal gate: zero production traffic on the version for at least 30 consecutive days, plus direct confirmation from any client that was still calling it in the final 90 days.

Deliverable

Produce a versioning policy document containing: the chosen scheme (date-pinned header or URI) with the cadence rationale, the breaking-vs-additive classification table your team applies to every change, the tolerant-reader clause for the client contract, the shim architecture note (where transforms live, how one is added and removed), the pinning rule for new integrations, and the deprecation runbook - notice periods, Deprecation/Sunset header emission, migration-doc link, and the usage-based removal gate. For an in-flight change, also deliver its classification, the target version, and its concrete sunset date.

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 - "deprecated soon" trains clients to ignore you.
• Do NOT remove a version on the calendar date alone; verify the 30-day zero-traffic gate first, or the sunset becomes an outage.
• 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.