api-versioning-strategy

name	api-versioning-strategy
description	Choosing and operating an HTTP API versioning strategy that doesn't break clients — Stripe's date-based pinned versions, the Deprecation/Sunset header pair (RFC 9745 + RFC 8594), URI vs header vs media-type approaches, and the version-transformer pattern. Grounded in Stripe's published architecture and IETF RFCs.
category	API Design
tags	["api","versioning","http","rest","deprecation","backward-compatibility","breaking-changes"]
allowed-tools	Read, Grep, Glob, Edit, Write, Bash(grep:*, rg:*, find:*, curl:*)

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

Symptom	Section
"Need to break a field but have 100k API keys"	Date-pinned versions
"Should I do /v1/ vs Accept: application/vnd.foo.v2+json?"	Strategy comparison
"How do I tell clients an endpoint is going away?"	Deprecation + Sunset
"Maintaining 6 versions in code is killing us"	Version transformers
"Internal API — do we even need versioning?"	Internal vs public

---

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:

Property	Why it works
Per-account default version (set on first call)	New customers automatically pinned to latest; existing customers don't break when you ship a change
Stripe-Version header overrides the pin per-request	Allows gradual client migration: SDK can opt-in to a new version before the account does
Date-based names (2024-04-10)	Conveys recency; no debate about what "v3" means; allows arbitrarily many small breaks instead of saving them up for a big-bang v3
Dashboard upgrade path	Customer can preview the diff, then upgrade their account-default version

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

Strategy	Where the version lives	Pro	Con	Best for
URI segment (/v1/, /v2/)	Path	Cache-friendly (different URL = different cache entry); zero client config	Can't make small breaks; forces a tree fork; URLs are no longer "stable resource identifiers" (per Fielding)	Internal APIs, public APIs that rarely break
Custom header (Stripe-Version: 2024-04-10)	Request header	Tons of versions cheap; per-request granularity	Can't share URLs with version baked in; harder to test in browser address bar	Public APIs at scale
Accept media-type (Accept: application/vnd.foo.v2+json)	Standard Accept header	"Spec-correct" per HTTP; reuses content negotiation machinery	Awkward to set; tooling support varies; debugging via curl is verbose	Hypermedia APIs, deeply RESTful designs
Query parameter (?version=2)	URL	Easy to test; visible in logs	Pollutes URL; semantically wrong (version isn't a resource property)	Rapid prototyping only
No versioning, additive only	n/a	Zero overhead; no client coordination	Can never make a breaking change without a new endpoint	Internal microservices with shared deploy

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(() => t.(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:

	Internal	Public
Coordinated deploy possible?	Yes — atomic swap	No — clients deploy independently
Schema evolution	Additive + Slack message	Strict versioning + email + dashboards + blog post
Sunset window	Days to weeks	6-24 months
Versioning need	Often none — just Deprecation headers	Mandatory
Best strategy	Additive evolution; URI version only on rewrite	Date-pinned headers (if scale warrants), URI for major rewrites

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

Anti-pattern	Why it bites	Fix
Bumping /v1/ to /v2/ for one breaking change	Forces clients to migrate everything for one field	Date-based version OR additive evolution
Removing endpoints with no Sunset header	Clients break with no warning; support tickets explode	Always pair removal with Deprecation 90+ days prior
Sending Deprecation but no Link	Clients know it's deprecated but not what to do	Always include Link: <migration-doc>; rel="deprecation"
Per-customer hardcoded version exemptions	Becomes unmaintainable; can't reason about behavior	Use the transformer pattern; "exemptions" become version pins
Versioning internal APIs like public ones	Process overhead with no payoff	Additive evolution + atomic deploys + Slack
Using semver (v1.2.3) on REST APIs	Implies meaning that doesn't apply (what's a "patch" to a JSON schema?)	Date-based names or major-only (v1)
Sunset date with no enforcement	Endpoint lives forever, code rots	Calendar reminder; CI test that fails 7 days before sunset to force action

---

Novice / Expert / Timeline

	Novice	Expert
First breaking change	Bumps /v1 to /v2, copy-pastes whole tree	Considers date-based pin, evaluates whether change is actually breaking
Telling clients about deprecation	Email blast	Deprecation + Sunset headers + Link + email + dashboard banner
Maintaining 5 versions	5 if/else branches in every controller	Transformer modules, latest-only core code
Sunset enforcement	"We'll get to it"	Sunset date in CI; endpoint becomes 410 Gone on the date
Internal API change	Same ceremony as public — slow	Additive evolution + atomic deploy; reserves heavy process for public

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