API Versioning and Backward Compatibility
On this page
Scenario: one field becomes three
The order API returns totalPrice. Finance now wants the response split into subtotal, tax and shipping. A mobile app released two years ago, a partner integration and four internal services all read totalPrice. Change it carelessly and some of them break on the next deploy, including app versions you can't force users to update.
Breaking vs non-breaking API changes
| Usually safe (backward compatible) | Breaking |
|---|---|
| Adding an optional field to a response | Removing or renaming a field |
| Adding a new endpoint | Changing a field's type or meaning |
| Adding an optional request parameter | Making an optional parameter required |
| Adding a new enum value (only if clients tolerate unknown values) | Changing URLs, status codes or error formats clients rely on |
Two habits make most changes safe:
- Clients ignore fields they don't know (the "tolerant reader"). Then adding fields never breaks anyone.
- Servers never remove a field that's in use. Deprecate first, measure usage, remove later.
Enums are the usual exception to "adding is safe". A .NET client deserializing "status": "on_hold" into a C# enum with JsonStringEnumConverter throws if OnHold isn't in its enum, so a new value on the server breaks every old client. Document that enums can grow, map unknown values to an Unknown member in clients you control, or add a new field rather than a new value for a critical change.
Mobile apps are the slowest clients of all: some users never update. Keep a minimum supported app version on the server, and let the app ask for it at startup, so you can require an upgrade instead of supporting an old version forever.
The pattern: expand, then contract
Most changes don't need a new version at all:
- Expand: add
subtotal,taxandshippingalongsidetotalPrice. Every existing client keeps working. - Migrate: document the new fields, mark
totalPricedeprecated (theDeprecationandSunsetHTTP headers are standard ways to signal it), and move internal consumers over. - Contract: once logs show nobody reads
totalPrice, remove it, or keep it forever if it's cheap.
The same expand-and-contract idea applies to database schemas (Day 58) and event payloads (Day 46).
API versioning schemes: when you need a new version
Some changes can't be additive: a different resource model, different semantics, a redesigned error format. Then publish a new version and run both side by side.
| Scheme | Example | Notes |
|---|---|---|
| URL path | /api/v2/orders | Most visible and common; easy to route and cache |
| Header | Api-Version: 2 | Clean URLs; easy to forget in clients |
| Media type | Accept: application/vnd.shop.v2+json | Precise, but less familiar |
| Date-based | Stripe-Version: 2024-06-20 | Each account pinned to a dated version; Stripe's approach |
Pick one scheme and use it everywhere. In ASP.NET Core, the Asp.Versioning packages support all of these.
How to deprecate and retire API versions
- Publish a deprecation policy: for example, an old version runs for 12 months after its successor ships.
- Measure usage per version and per client, so you know who to contact.
- Warn through headers, docs and email before the sunset date.
- For internal services, consumer-driven contract tests (such as Pact) let each consumer state what it relies on, so the provider's build fails before a breaking change ships.
Check yourself
Its enum doesn't have the new value, and the JSON deserializer throws on unknown enum strings. Treat new enum values as potentially breaking, and have clients map unknowns to a fallback.
Use expand and contract: add subtotal, tax and shipping alongside totalPrice, and keep filling both. Move consumers to the new fields, mark totalPrice as deprecated, and track who still reads it. Only remove it once usage reaches zero, or in a new API version.
Consumer-driven contract tests, for example with Pact. Each consumer publishes the parts of the API it relies on, and the provider's pipeline verifies every contract before deploying. A change that would break any consumer fails the build instead of production.
Adding optional request fields, new response fields and new endpoints is usually safe. Removing or renaming fields, changing types, making optional fields required and changing an enum's values can break clients, especially strict deserializers.
Announce a timeline, mark responses with Deprecation and Sunset headers, measure which clients still call it, contact them directly, and only switch it off when traffic is near zero or the published date arrives.