API Versioning Strategy

API Versioning Strategy

TL;DR: Date-based versions pinned per API key (Stripe's model) beat /v1/, /v2/ for long-lived public APIs because they let you make small breaking changes without forcing clients onto a new tree. For internal APIs, additive evolution + the Deprecation and Sunset headers (RFC 9745, RFC 8594) is usually enough. Always announce, always sunset on a date, never just remove.

Jump to your fire

Decision diagram

flowchart TD
  A[Need to change API behavior] --> B{Additive only?<br/>new field, new endpoint, new optional param}
  B -->|Yes| C[Just ship it<br/>no versioning needed]
  B -->|No, breaking| D{API is public<br/>+ many opaque clients?}
  D -->|No, internal/few clients| E[Coordinate migration<br/>+ Deprecation/Sunset headers]
  D -->|Yes, public| F{Can you rev compat layer<br/>per request?}
  F -->|Yes, have a transformer| G[Date-based pinned version<br/>Stripe model]
  F -->|No, big rewrite| H[Major-version URI bump<br/>/v1 → /v2]
  E --> I[Set Deprecation: @timestamp<br/>+ Sunset: HTTP-date<br/>+ Link: rel=deprecation]
  G --> I
  H --> I

1. Date-based pinned versions (Stripe's model)

Stripe published its architecture in API versioning at Stripe:

The first time a user makes an API request, their account is automatically pinned to the most recent version available, and from then on, every API call they make is assigned that version implicitly.

[Versions are] rolling versions that are named with the date they're released (for example, 2017-05-24).

The key properties:

This is the only approach that scales to truly long-lived public APIs (Stripe has versions going back a decade). It costs you internal complexity (the transformer pattern in §4) but spares your customers the perpetual /v1/ → /v2/ migration cycle.

2. Versioning strategy comparison

Pick by selecting your constraint:

• "We make tiny breaks frequently" → date-based header (Stripe)
• "We do a big rewrite every 5 years" → URI segment (/v1/, /v2/)
• "We never break, only add" → no versioning + additive evolution

3. The Deprecation/Sunset header pair

Two IETF RFCs cover the lifecycle signal:

Sunset header — RFC 8594

The Sunset value is an HTTP-date timestamp, as defined in Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the future.

Sunset: Sat, 31 Dec 2026 23:59:59 GMT

Indicates "the resource is expected to become unresponsive at a specific point in the future." Clients SHOULD treat the timestamp as a hint, not a hard contract.

Deprecation header — RFC 9745

Deprecation: @1735689599
Sunset: Sun, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-v1-to-v2>; rel="deprecation"

The Deprecation value is a Unix timestamp (seconds, prefixed with @ per Structured Fields). It can be in the past ("already deprecated") or future ("will be deprecated"). The MUSTs:

• MUST use the structured-field date format per RFC 9651
• Sunset MUST NOT be earlier than Deprecation — the spec is explicit; it's a temporal ordering constraint
• SHOULD include a Link with rel="deprecation" pointing to migration docs

The act of sending Deprecation does not change the resource's behavior — it's a signal, not a degradation. Servers SHOULD keep the resource functional through the Sunset date (modulo emergencies).

Recommended timeline

T+0      First Deprecation: header sent in production
T+30d    Public announcement (changelog, email, docs)
T+90d    Add response logs / metrics on usage of deprecated path
T+180d   Sunset date set 90 days out
T+270d   Sunset date arrives — endpoint returns 410 Gone with migration link

For minor breaking changes on a major-version-pinned API: 6 months is the median. For full v1 → v2 sunsets: 12-24 months.

4. The version-transformer pattern

Stripe's internal architecture solves the "we have 50 versions in production" problem:

[The system uses] API resource classes that define current API response structures, combined with version change modules that encapsulate backwards-incompatible transformations. When processing responses, the system walks back through time and applies each version change module that it finds along the way until that target version is reached.

The shape:

// resource: the canonical (latest) representation
const charge = {
  id: 'ch_123',
  amount: 1000,
  payment_method_details: { card: { brand: 'visa', last4: '4242' } },
}

// Each breaking change is one transformer module:
const v_2024_03_01 = {
  // Removes 'card' nesting under payment_method_details, flattens fields
  apply(resource) {
    return {
      ...resource,
      card_brand: resource.payment_method_details?.card?.brand,
      card_last4: resource.payment_method_details?.card?.last4,
    }
  },
}

const v_2023_10_15 = {
  // Renames 'amount' to 'amount_cents'
  apply(resource) {
    const { amount, ...rest } = resource
    return { ...rest, amount_cents: amount }
  },
}

// Pipeline applies transformers in reverse-chronological order
// until requested version is reached
function transform(resource, requestedVersion) {
  const chain = transformers.filter(t => t.date > requestedVersion)
  return chain.reduceRight((r, t) => t.apply(r), resource)
}

The wins:

• Core code stays modern — every endpoint is written against the latest schema; no if (version < ...) sprinkled through business logic.
• Each break is one file — easy to review, easy to test in isolation, easy to delete when the last user pins past it.
• Telemetry — you can count which transformers fire per day to plan deprecations against actual usage.

The cost: building the transformer framework. Worth it if you have >3 breaking changes per year and >10k API consumers; overkill for a <50-customer internal API.

5. Internal vs public APIs

The asymmetry matters:

The trap: companies treat all APIs as "public" and build the heavy versioning infrastructure for an API used only by 3 internal services. The reverse trap: a leaked internal API has external consumers and you can't actually break it.

Defense: make "public" a binary tag on the service. Public services get the full versioning ceremony; internal services don't, but get aggressive monitoring of who's calling them.

Anti-patterns

Novice / Expert / Timeline

Timeline test: how long does it take from "we want to remove field X" to "field X is gone in production"? An expert org has a single repeatable answer (e.g., 90 days). A novice org has no answer because there's no process.

Quality gates

A versioning change ships when:

• Test: Removing or renaming any externally-visible field is gated on a deprecation announcement at least N days old (where N is the documented sunset window).
• Test: Every deprecated endpoint sends Deprecation: @<unix-ts> and Sunset: <HTTP-date> headers, verified in an integration test.
• Test: Sunset value is never earlier than Deprecation value (per RFC 9745 MUST).
• Test: Every deprecation announcement includes a Link: <docs-url>; rel="deprecation" header AND a public migration doc that exists at that URL (HEAD check in CI).
• Test: Usage telemetry per version exists — you can answer "how many requests on the v2 path yesterday?" before you delete v2.
• Test (date-pinned only): New API keys default to the latest version; existing keys hold their pin across deploys.
• Manual: Sunset enforcement plan: a calendar reminder, a CI check, or an automated 410 Gone — something fires when the date arrives.

NOT for this skill

• GraphQL schema evolution (use graphql-schema-evolution)
• gRPC / Protobuf wire-compatibility (use protobuf-evolution-rules)
• Database schema versioning (use zero-downtime-database-migration)
• Library / SDK semver (use npm-package-versioning)
• Event-stream schema evolution (use kafka-schema-registry-design)

Sources

• Stripe: API versioning at Stripe — pinned date-based versions, transformer pattern
• Stripe API: Idempotent requests / versioning policy
• IETF: RFC 8594 — The Sunset HTTP Header Field
• IETF: RFC 9745 — The Deprecation HTTP Header Field
• IETF: RFC 9651 — Structured Field Values for HTTP (date format for Deprecation header)
• Roy Fielding: REST APIs must be hypertext-driven — the canonical argument against URI versioning