Notesencoding🌱 seedling

API Versioning

Also: API Version · Versioned API · Version Pinning · Breaking Change · Dated Versioning

API versioning lets a service make breaking changes without breaking clients it doesn't control, by letting each client keep the version it was built against. Additive changes need no version, as long as clients ignore unknown fields.

Why it exists

Public API clients upgrade on their own schedule, or never. The server must keep serving every shape it ever promised, for years.

How it works

  • Additive, no version needed: new endpoints, optional parameters, new response fields.
  • URL major versions (/v1/, /v2/): simple and visible, but each version is effectively a separate API to maintain.
  • Dated versions in a header: GitHub's X-GitHub-Api-Version (first version 2022-11-28; an old version stays supported for at least 24 months after a newer one ships).
  • Pinning + transformation (Stripe): an account is pinned to the version current at its first request; Stripe-Version overrides per request; core code builds the latest response and it is walked back through one version change module per breaking change.

Trade-offs

Approach Gains Costs
URL major version obvious, cache-friendly big-bang migrations, parallel codebases
dated header small, frequent changes clients must send it; support windows to manage
pin + transform modules old versions isolated from core code transformation layer to build and test

In practice

  • Stripe handled almost a hundred backward-incompatible changes in six years this way (as of 2017), keeping every version since 2011 working. Since 2024-09-30.acacia it ships monthly non-breaking versions and twice-yearly major releases.

Pitfalls

  • Clients that fail on unknown fields or enum values: then even additive changes break them.
  • Webhooks and events need versioning too, not just request/response.

Recall

These cards are also in your review deck, scheduled with spaced repetition.