API Versioning

The Problem

APIs are contracts with external consumers. Once published, changing a response shape, removing a field, or altering behavior can break thousands of integrations. Yet APIs must evolve — new features, performance improvements, and security fixes require changes. API versioning lets you introduce breaking changes without disrupting existing clients by maintaining multiple versions simultaneously. The challenge is choosing a versioning strategy, managing the lifecycle of each version, minimizing code duplication across versions, and eventually sunsetting old versions gracefully.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Additive Changes vs Breaking Changes

Not every change requires a new API version. Understand what’s breaking and what’s not.

Non-breaking (additive) changes — safe to deploy without versioning:

• Adding a new optional field to the response
• Adding a new optional query parameter
• Adding a new endpoint
• Adding a new enum value (if clients handle unknown values)
• Increasing rate limits
• Adding new webhook event types

Breaking changes — require a new version:

• Removing or renaming a field in the response
• Changing a field’s data type (string → number)
• Making a previously optional parameter required
• Changing the URL structure
• Removing an endpoint
• Changing error response format
• Changing authentication mechanism
• Altering the semantics of an existing field

Best practice: Design APIs to be as additive as possible. Use nullable fields, optional parameters, and extensible enums from day one. This minimizes the frequency of breaking changes and the need for new major versions. Many successful APIs (Stripe, Twilio) have maintained backward compatibility within a single version for years through careful additive evolution.

The Stripe Date-Based Versioning Model

Stripe uses a unique versioning approach that’s become an industry model.

How it works:

• Each API key is pinned to the version that was current when the key was created (e.g., 2024-01-15)
• Breaking changes are released as new dated versions (2024-06-01)
• Clients can override their pinned version per-request with a header: Stripe-Version: 2024-06-01
• All changes between versions are documented with exact diffs

Implementation: Internally, Stripe maintains a chain of version transformers. The latest code always runs, and a series of backward-compatibility layers transform the response to match the requested version. When a client requests version 2024-01-15, the response passes through transformers for every version between 2024-01-15 and the current version — each transformer reverting one breaking change.

Benefits:

• No URL changes — ever
• Clients upgrade on their own schedule
• Each breaking change is individually documented and revertible
• New integrations automatically get the latest version

Drawbacks:

• Complex transformer chain for old versions (technical debt)
• Testing matrix grows with each version
• Must maintain backward compatibility layers indefinitely (or until sunset)

Version Sunset Strategy

Old versions can’t live forever — they accumulate technical debt and security risk.

Sunset timeline:

1. Announce deprecation: 6-12 months before sunset. Add Deprecation header to all responses. Send email to all API consumers using the deprecated version.
2. Migration period: Provide a detailed migration guide with before/after examples. Offer office hours or support for complex migrations.
3. Warning escalation: 3 months before sunset, start returning Warning headers. Log deprecated version usage and reach out to top consumers.
4. Sunset: Return 410 Gone for all requests to the sunset version. Include the migration guide URL in the error response body.

Sunset headers (RFC 8594):

• Deprecation: Sat, 01 Jan 2025 00:00:00 GMT
• Sunset: Sat, 01 Jul 2025 00:00:00 GMT
• Link: </docs/migration-v1-v2>; rel="deprecation"

Decision criteria for sunset:

• Less than 1% of total API traffic on the old version
• All major consumers have migrated (verify via usage metrics)
• Security vulnerabilities in the old version that can’t be patched
• Maintaining the old version blocks a critical feature or infrastructure change

Never sunset without notice: Even if traffic is near-zero, always announce. Someone’s production integration might only run monthly.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: API Versioning

You are an expert software architect and teacher. I want to understand api versioning as a practical system design capability. (Backward-compatible API evolution with URL, header, and content negotiation strategies).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

APIs are contracts with external consumers. Once published, changing a response shape, removing a field, or altering behavior can break thousands of integrations. Yet APIs must evolve — new features, performance improvements, and security fixes require changes. API versioning lets you introduce breaking changes without disrupting existing clients by maintaining multiple versions simultaneously. The challenge is choosing a versioning strategy, managing the lifecycle of each version, minimizing code duplication across versions, and eventually sunsetting old versions gracefully.

## Architectural Approaches

<ApproachList>
<Approach
  name="URL Path Versioning"
  pros={[
    'Most explicit and visible — version is obvious in every request',
    'Easy to route at the load balancer or gateway level',
    'Simple to cache (different URLs = different cache entries)',
    'Easy to document and test each version independently',
  ]}
  cons={[
    'URL changes break bookmarks and hardcoded links',
    'Can lead to URL proliferation (/v1, /v2, /v3...)',
    "Philosophically impure — the version isn't part of the resource identity",
    'Harder to share common logic across versions without duplication',
  ]}
>
Include the version in the URL path: `/api/v1/users`, `/api/v2/users`. The most visible and widely used approach. Each major version is a distinct URL namespace.
</Approach>
<Approach
  name="Header-Based Versioning"
  pros={...

[Full prompt copied to clipboard]