Reliability & Scale · Lesson 01

API Versioning

Change is inevitable — clients are not. Versioning is the mechanism that lets a provider evolve a contract while the callers who depend on the old one keep running undisturbed.

Why versioning exists at all

Think of a published dictionary. Once a word is in print, every reader who owns a copy depends on that definition. If the publisher changes "literally" to mean "figuratively" mid-edition without issuing a new volume, every existing owner is reading a different book than they think. Software contracts have the same problem — except the readers are machines that never tolerate inconsistency.

An API version is the edition number on the dictionary spine. It signals: "this is the promise I made in October 2022; that is the promise I make today." Clients pin to a specific edition so they know exactly what they're getting.

Breaking vs additive changes

Not all changes are equal. The key distinction:

The engineering rule of thumb: you can add, but you must not remove or change the shape of anything already published. If you must do so, you need a new version.

Three versioning strategies

1. URI path versioning

The version lives in the URL itself: /v1/users, /v2/users.

GET /v1/users/42          # old clients keep using this forever
GET /v2/users/42          # new clients opt in here

Pros: The version is immediately visible in logs, browser history, and documentation URLs. Easy to route in a reverse proxy. Developers can paste a link and be unambiguous about which version they mean.

Cons: Technically violates REST purity — the same resource now has two different stable URLs, which can confuse caches and links. Encourages large version increments ("v2 is totally new!") rather than fine-grained changes.

2. Custom request-header versioning

The version travels in a custom header rather than the path.

GET /users/42 HTTP/1.1
Host: api.example.com
Api-Version: 2024-03-01   # date-based version — Stripe's approach

Pros: The URL is "clean" and permanent — bookmarks and caches reference a single endpoint. Works well with date-stamped versioning (Stripe uses this), which makes deprecation timelines obvious.

Cons: Invisible in a URL. Curl newcomers forget to add it. Requires API gateways to forward or interpret the header. Harder to test in a plain browser bar.

3. Media-type (Accept) versioning

The client signals its desired version in the HTTP Accept header using a vendor MIME type.

GET /users/42 HTTP/1.1
Host: api.example.com
Accept: application/vnd.myapp.v2+json

Pros: Maximally RESTful — a single canonical URL for each resource; version is part of content negotiation. Follows the design intent of HTTP's Accept header.

Cons: Highest cognitive overhead. Very few developers know to look for it. Server-side content negotiation machinery is nontrivial to implement and test. Rarely used outside high-ceremony APIs.

Comparison at a glance

Backward compatibility and the "Robustness Principle"

Jon Postel's old networking maxim — be conservative in what you send, liberal in what you accept — maps naturally to versioning. On the server side: never remove a field without a deprecation window, never change a field's type silently. On the client side: ignore unknown keys, tolerate new enum values you haven't seen before. If both parties hold to this, additive changes never break anything and a new version is only needed for genuinely incompatible changes.

Deprecation policy and the Sunset header

A version no one can ever remove is a support liability. A clear deprecation policy lets teams plan migrations. The minimum viable policy has four components:

1. Announce the planned end-of-life date at least 6–12 months in advance (longer for well-adopted public APIs).
2. Signal in-band via the Sunset HTTP response header (RFC 8594) so monitoring tools can catch it automatically.
3. Email/notify registered integrators so humans are also in the loop.
4. Remove only after the announced date; return 410 Gone with a pointer to the current version.

# Response from a deprecated v1 endpoint
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

{ "id": 42, "name": "Ada Lovelace" }

The Sunset header value is an HTTP-date marking when the endpoint will stop responding. Monitoring tools and SDKs can parse this header and surface a warning dashboard entry automatically — no human polling required.

Under the hood: how versioning is actually dispatched

When a request arrives, something has to read the version signal and route it to the right handler. The mechanism differs by strategy — and understanding it makes clear why misconfiguration produces silent breakage rather than obvious errors.

URI path routing

The gateway or web framework simply prefix-matches the URL path. In nginx this is a location block; in Express it is a router mount; in AWS API Gateway it is a stage or base-path mapping. The rule is literal string matching — there is no version inference or fallback.

# nginx — two version prefixes proxied to different upstream groups
location /v1/ {
    proxy_pass http://api_v1_upstream/;   # v1 pod pool
}
location /v2/ {
    proxy_pass http://api_v2_upstream/;   # v2 pod pool
}
# A request for /v3/users gets a 404 — there is no location block for it.
# A request for /users (no prefix) also gets a 404 unless you add a default.

The v1 and v2 upstream groups can be separate deployments, or the same application code with a version environment variable controlling which handler module loads. Shared code typically lives behind a shared data access layer that both versions call — each handler transforms the request/response shape, but the database logic is common.

Custom-header routing

The gateway must inspect a non-standard header before routing. In Envoy or Kong this is a header-match rule; in application middleware it is a guard that reads the header early in the pipeline.

# Express middleware — read Api-Version header, attach to req
app.use((req, res, next) => {
  req.apiVersion = req.headers['api-version'] || '2024-01-01';  // default to oldest stable
  next();
});

# Route handler chooses behaviour based on the attached version
app.get('/users/:id', (req, res) => {
  if (req.apiVersion >= '2025-03-01') {
    return serveV2User(req, res);  // new response shape
  }
  serveV1User(req, res);          // legacy shape
});

A common gotcha: if no default version is set and the header is absent, the server either 400s or silently uses the latest — both can surprise callers. Be explicit about the default.

Content negotiation (Accept header)

The server parses the Accept header using standard HTTP content negotiation. The client sends a vendor MIME type; the server looks for a handler registered under that type and returns a matching Content-Type in the response.

# Request
GET /users/42 HTTP/1.1
Accept: application/vnd.myapp.v2+json, application/json;q=0.8

# Server selects the highest-preference type it supports
# If it supports v2: 
HTTP/1.1 200 OK
Content-Type: application/vnd.myapp.v2+json

# If v2 is not implemented, falls back to application/json (q=0.8)
HTTP/1.1 200 OK
Content-Type: application/json    # ← v1 shape, silently

That silent fallback is the main danger: a client that requests v2 can receive v1 data without a clear error if the server does not strictly enforce the negotiation. The server should return 406 Not Acceptable if it cannot serve the requested version type at all.

How two versions share code

The pattern used by Stripe, GitHub, and most mature APIs is a transformation layer: the canonical data model and business logic live in one place; version adapters sit at the request/response boundary and translate between the current shape and each supported version's shape. When v1 is sunset, you delete one adapter file — the core logic is untouched.

# Shared handler pattern
def get_user(user_id):
    user = db.get_user(user_id)       # one data access call
    return user                         # canonical model object

# Version adapters
def serialize_v1(user): return {"id": user.id, "amount": user.fee_usd}
def serialize_v2(user): return {"id": user.id, "fee_minor_units": user.fee_cents}

How to debug & inspect it

The most common versioning bug is a client receiving the wrong version's response without realising it — either because the version signal was silently ignored or because the server defaulted differently than expected. Three tools cover the diagnostic space: curl -I, DevTools Network, and the headers themselves.

Confirm which version was actually served

Read Deprecation and Sunset headers programmatically

Symptom → cause → fix

1. After any deploy, curl -I a versioned endpoint and confirm the echoed version matches what you deployed.
2. In DevTools, check the api-version (or equivalent) response header on every call to catch silent rollbacks or misrouting.
3. Monitor for Deprecation: true and Sunset headers in your integration test suite or API client wrapper — surface them as CI warnings before they become production surprises.
4. When a "client broke after a change" ticket arrives, first confirm which version it was calling (check request logs for the version prefix or header), then diff that version's response schema against what the client expected.
5. If a header version is going missing in transit, run curl -v and compare request headers sent vs. received at the server side (via access logs with header capture).

In production: how leading APIs do it

Versioning decisions made at a platform's founding tend to outlast every other architectural choice — they shape client SDKs, third-party integrations, and support burden for years. Examining how five platforms solved the problem reveals that the stakes are high enough that each arrived at a different answer, and each answer reflects specific operational priorities.

Deep-dive: Stripe's account-pinning model

Most versioning schemes require clients to specify which version they want. Stripe inverts this: when a developer creates an account, the platform records the API version that was current on that day, and all subsequent requests from that account use that version by default — permanently. The client never has to remember to send a version header to stay stable, because the server remembers it for them.

The operational consequence is profound. When Stripe ships a breaking change, it publishes it under a new date-version. Existing accounts see nothing different — their pinned version still routes to the old behaviour. The developer who wants the new feature upgrades their pin deliberately in the Dashboard, reads the migration guide, and updates their integration code before flipping the switch. There is no accidental breakage, no emergency rollback, and no coordinated cutover.

Additive changes — new response fields, new optional request parameters, new endpoints — ship to all versions simultaneously. This keeps the number of parallel code paths manageable: the codebase only forks on genuinely incompatible changes, not on every incremental addition. The result is that Stripe maintains a relatively small number of distinct schemas despite a long history of changes, because the date-version tag only creates a new fork when truly necessary.

This model is widely considered the gold standard for "evolve without breaking anyone" because it shifts the upgrade decision entirely to the consumer and makes the default safe. The cost is operational complexity on the provider side: every breaking change requires a version transformer, and old versions must stay alive indefinitely until the last pinned account upgrades. Stripe handles this by tracking, in real time, how many accounts are still on each version — and only retiring a version once the population drops to zero.

How leading APIs do it

Sources & further reading

• Stripe Engineering — API Versioning — how Stripe uses date-based custom header versioning in practice
• Google API Design Guide — Versioning — opinionated guidance for large-scale API design including breaking-change classification
• RFC 8594 — The Sunset HTTP Header Field — IETF specification for machine-readable deprecation signaling
• MDN — Deprecation header — companion to Sunset for in-band deprecation notices