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