API Versioning Strategies Lab (Interactive)

Ship breaking schema changes and see how URI, query, header, and Stripe-style date versioning keep legacy SDKs alive. Pin a client to a historical version, release renames and field reshaping server-side, and compare controllers versus mutator chains for each versioning strategy.

API Versioning Strategy Lab

Ship breaking schema changes and see how each strategy keeps a legacy client's payload intact.

Client SDK pinned to:

Schema changes shipped since 20222/3

GET /v1/charges/ch_9082 HTTP/1.1
Stripe-Version: 2022-01-01

{
  "id": "ch_9082",
  "status": "2026-04-12T14:30:00Z",
  "phone_number": "+1-206-555-0134",
  "source": {
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  },
  "amount_cents": 12950
}

Transformation chain (reverse-chronological mutators):

[breaking] undo 2023 change: Flattened source.card to top-level brand/last4

[breaking] undo 2025 change: Renamed "amount_cents" (int) to "amount" (string)

Controllers in backend

Mutators applied

Breaking vs client

Client outcome

translated

2 breaking change(s) post-date this SDK. The date engine replays 1 core controller through mutators to emit the 2022 shape — no v2022Controller exists.

One canonical URI, version rides in the header — cache-friendly like URI path, but invisible in browser URLs.

How It Works Under the Hood

Servers evolve but thousands of installed mobile apps and partner integrations cannot upgrade on command, so breaking changes — renames, type changes, deletions — must be absorbed by a versioning strategy. URI path and query versioning give gateways visible routing but force a parallel controller per major; header negotiation keeps URIs pristine but needs Vary cache keys; Stripe’s date-pinned approach runs one latest-schema controller and replays reverse-chronological response mutators, supporting hundreds of historical versions without code duplication.

Core Architectural Principles

Additive changes (optional fields, new endpoints) are non-breaking and need no version bump.
Date-based pins route one core controller through reverse mutators instead of duplicating v1/v2/v3 code.
RFC 8594 Sunset and Deprecation headers plus brownout windows retire old versions gracefully.

Interview Round Script

Lead with preferring additive non-breaking changes, then pick a strategy with trade-offs: URI versioning for gateway visibility on public APIs, date-based Stripe-style pinning when you must support long-tail integrations without controller sprawl. Finish with deprecation mechanics: telemetry on who still calls v1, Sunset headers, a chaos brownout, then 410 Gone.

Key Trade-Offs

Every supported version is operational debt: parallel controllers double testing surface while mutator pipelines hide schema drift inside middleware.

Related Curriculum Chapter