Part 6 · 1 chapters · ~8 min
Versioning and Deprecation
Additive change as the default, tolerant clients, what counts as breaking, URL, header and date-based versioning (Stripe-style), deprecation and sunset headers, tracking usage per version, and migration support.
13
Evolve, version, retire
| versioning style | example | notes |
|---|---|---|
| URL major version | /v1/transfers | simple, visible, cache-friendly; most common |
| header | Accept: application/vnd.bank.v2+json | clean URLs, harder to test in a browser |
| dated versions | Bank-Version: 2026-09-01 | Stripe-style: each account pinned to a date; server transforms responses through version gates |
EVOLVING AN API WITHOUT BREAKING CLIENTS
additive first; versions and sunsets only when you must
swipe the figure sideways, or tap expand for full screen
1/5
additive change
Adding optional request fields, response fields, endpoints and (carefully) enum values does not break well-behaved clients. Most evolution should be additive.
add, do not changeoptional fields, new endpoints