Versioning Strategies

The best version is the one you never need: evolve additively and make clients tolerant readers. When breaking changes are unavoidable, choose one strategy and apply it everywhere. URL major versions (/v1) are simple and visible; header/query versions (api-version=2026-10-01, Microsoft) keep URLs stable; media-type versions are precise but awkward; date-based versions pinned per account (Stripe) let you ship small breaking changes while each customer upgrades on their schedule — powerful but needs version transformation layers.

Criterion	URL (/v2)	Header / query (api-version)	Media type	Date-pinned per account
Visibility	High	Medium	Low	Medium
Caching/routing	Easy	Needs Vary/header routing	Needs Vary	Server-side
Granularity	Big-bang majors	Per release	Per resource	Small, frequent
Server complexity	Parallel stacks	Medium	Medium	High (transform layers)
Used by	Many public APIs	Azure (api-version), GitHub (X-GitHub-Api-Version)	Some hypermedia APIs	Stripe

# Stripe-style: account pinned to a version, override per request
POST /v1/charges
Stripe-Version: 2026-09-30

# Internally: request → latest model → chain of version transformers → response for 2026-09-30

Common pitfalls

Versioning for every additive change.
Major versions that fork codebases forever.
No defined support window for old versions.

Key points

Avoid breaking changes; tolerant readers
One strategy, applied consistently
Defined support windows

Further reading: Stripe: APIs as infrastructure (versioning)

Practice questions

How does Stripe's date-based versioning work?

Answer

Each account is pinned to the API version current when it integrated; requests can override with a header. The server runs the latest logic and applies backwards transformations to produce responses in the older version's shape.

What's the main downside of URL major versions?

Answer

Breaking changes get batched into big releases and teams often maintain parallel codebases/infrastructure for each major version for years.