API Versioning

An API is a promise to callers you often can't see or contact. The moment a client depends on a response shape, that shape is load-bearing — changing it breaks code you don't control and may never hear about until it's in production. Versioning is the set of conventions for making changes anyway, without breaking everyone who already integrated.

1Breaking vs. Non-Breaking Changes

The entire discipline rests on being able to classify a change correctly.

Non-breaking (safe to ship without a version bump):

• Adding a new optional field to a response
• Adding a new endpoint
• Adding a new optional request parameter with a sensible default
• Adding a new enum value, if clients are contractually required to handle unknown values gracefully
• Relaxing a validation rule (accepting more input than before)

Breaking (requires a version bump or a migration path):

• Removing or renaming a field
• Changing a field's type ("id": 42 -> "id": "42")
• Changing the meaning of a field without changing its name
• Adding a required request parameter
• Changing a status code an existing case returns
• Tightening validation (rejecting input that used to be accepted)
• Changing pagination defaults, sort order, or error shapes

// Before
{ "user": { "id": 42, "name": "Ada" } }

// Non-breaking: added field
{ "user": { "id": 42, "name": "Ada", "email": "ada@example.com" } }

// Breaking: type changed on an existing field
{ "user": { "id": "42", "name": "Ada" } }

A useful test: could a client written against the old contract, with reasonable-but-not-paranoid parsing, keep working unmodified? If yes, it's additive. If the client would throw, silently misbehave, or receive different data under the same call, it's breaking.

2URI Path Versioning

The most visible and most common strategy — the version is baked into the URL:

GET /v1/orders/42
GET /v2/orders/42

Pros: trivially cacheable per version (different URL = different cache key), visible in every log line and every curl command, trivial to route at the load balancer/gateway level to entirely different backend deployments.

Cons: the URI is supposed to identify a resource, and /v1/orders/42 and /v2/orders/42 arguably identify the same order — versioning the path conflates "which resource" with "which representation of the contract." REST purists consider this a layering violation. In practice it's the dominant approach anyway (Stripe, GitHub, Twilio) because operational simplicity usually wins.

3Header-Based Versioning

The URL stays stable; the version travels in a request header.

GET /orders/42
Accept: application/vnd.myapi.v2+json

or a custom header:

GET /orders/42
Api-Version: 2026-03-01

Pros: keeps the URI a pure resource identifier; the Accept header form uses content negotiation, which is what HTTP designed headers for in the first place.

Cons: invisible to a quick glance at logs or a browser address bar; harder to test ad hoc (curl needs an extra flag); intermediary caches and proxies key on URL by default, so header-based variance needs Vary: Api-Version to cache correctly at all.

4Query Parameter Versioning

GET /orders/42?version=2

Rare as the primary mechanism (it's easy to omit accidentally, and mixes control metadata into the same namespace as filters), but common as a fallback or for quick manual testing alongside another scheme.

5Date-Based Versioning

Instead of integers, the version is the date the contract was frozen — Stripe's approach:

GET /v1/charges/ch_123
Stripe-Version: 2024-06-20

Every account has a pinned default version (usually the date it was created), and it only moves forward when the integrator explicitly opts in by requesting a newer date. Internally the server keeps a table of transformation functions between consecutive dated versions and pipes an old request through however many transforms are needed to reach current internal logic, then pipes the response back down.

request (pinned: 2023-01-01) -> [transform 2023-01-01 -> 2023-06-01] -> [transform ... -> current] -> internal handler
response (current shape)     -> [transform current -> ... ] -> [transform ... -> 2023-01-01 shape] -> client

This scales far better than maintaining N parallel full implementations — there's one current implementation and a chain of small, independently testable shape-adapters.

6Semantic Field-Level Versioning

Instead of versioning the whole API, version individual capabilities via feature flags or field opt-ins:

GET /orders/42
X-Enable-Features: new-pricing-model,extended-status

This avoids the combinatorial explosion of "v1 vs v2 vs v3 of the entire surface" when only one field actually changed, but it's harder to reason about which combination of flags a given client is actually running with, and testing the full cross-product of flags is often skipped in practice.

7What to Version: The Whole API vs. a Single Resource

Most real systems don't cleanly bump "the whole API" at once — a single breaking change to one resource doesn't require every other resource to also gain a /v2/. Two structures:

/v1/orders, /v1/customers, /v1/products      (global version — simple, coarse)
/v2/orders, /v1/customers, /v1/products      (per-resource — only orders changed)

Per-resource versioning avoids forcing clients who only touch /customers to migrate when /orders changes, but it means "v1" and "v2" are no longer single coherent labels — the docs must state, per resource, which version is current.

8Deprecation Policy

A version bump is only half the story — the old version has to eventually go away, on terms clients can plan around.

GET /v1/orders/42 HTTP/1.1

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrating-to-v2>; rel="deprecation"

• Deprecation (a draft RFC header, widely adopted) marks a response as coming from a deprecated endpoint.
• Sunset (RFC 8594) gives the exact date the endpoint stops responding entirely.
• A documented minimum notice period (commonly 6–12 months for public APIs) is a trust commitment, not just a courtesy — integrators build migration schedules around it.

A responsible sunset also actively measures usage of the old version before killing it — deprecation headers are easy to ignore, and traffic dashboards per version are the only reliable signal that migration has actually happened.

HTTP/1.1 200 OK
Vary: Api-Version
Cache-Control: max-age=60

type Transform = (payload: unknown) => unknown;

const transforms: Record<string, Transform> = {
  "2023-01-01": (p: any) => ({ ...p, status: p.state }),        // renamed state -> status later
  "2023-06-01": (p: any) => ({ ...p, amount_cents: p.amount }), // amount -> amount_cents later
};

⚠️ Common Pitfalls

1. No versioning strategy decided before the first breaking change is needed. Retrofitting a scheme onto a live API with existing integrators is far more disruptive than picking one (even url path, the simplest) on day one.
2. Bumping the major version for non-breaking changes. This trains integrators to fear version bumps and ignore changelogs, because "v2" stops reliably signaling "you must act."
3. Never actually removing old versions. A "deprecated" endpoint with no enforced sunset date accumulates forever, multiplying the surface area every future change must consider.
4. Versioning too granularly (per-field flags) without a discovery mechanism. If clients can't query which flags exist and what they do, the feature-flag approach in section 6 becomes an undocumented maze.
5. Silently changing behavior at the same version/URL. If Api-Version: 2 behavior is allowed to drift over time without a new version, "v2" stops being a stable contract at all — the version identifier only means something if it's frozen once published.
6. Forgetting Vary with header-based versioning. As covered in Under the Hood, this causes cache poisoning across versions that is very hard to diagnose because it appears intermittent (depends on cache state).
7. No default/pinned version for new integrators. If omitting the version header silently means "whatever is newest today," a client's behavior can change out from under it the next time the API adds a version, with no code change on their end at all.

📋 Quick Reference

URI path       /v1/orders          simple, cacheable, visible; conflates resource + contract
Header         Accept: application/vnd.api.v2+json    clean REST; needs Vary; less visible
Query param    ?version=2          rare as primary; easy to omit
Date-based     Api-Version: 2026-03-01   Stripe-style; needs a transform chain

Classify first  additive/optional -> safe | removed/renamed/retyped/tightened -> breaking
Deprecation     Deprecation: true
                Sunset: <RFC 1123 date>
                Link: <...>; rel="deprecation"

Cache safety    Vary: Api-Version   REQUIRED for header-based versioning behind any cache
Contract rule   "clients MUST ignore unknown fields" turns additive changes into safe ones
Transform chain one current impl + N small pure functions between consecutive versions

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: api_api_versioning_theory.md · generated by tools/build_lessons.py