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

Content truncated.