Catalog My learning Blog
System Design Roadmap: 100-Day Course for Engineers · Phase 6 · Lesson 55 · 4 min read

API Versioning and Backward Compatibility

On this page
  1. Scenario: one field becomes three
  2. Breaking vs non-breaking API changes
  3. The pattern: expand, then contract
  4. API versioning schemes: when you need a new version
  5. How to deprecate and retire API versions
  6. Check yourself

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 responseRemoving or renaming a field
Adding a new endpointChanging a field's type or meaning
Adding an optional request parameterMaking 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:

  1. Expand: add subtotal, tax and shipping alongside totalPrice. Every existing client keeps working.
  2. Migrate: document the new fields, mark totalPrice deprecated (the Deprecation and Sunset HTTP headers are standard ways to signal it), and move internal consumers over.
  3. 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.

SchemeExampleNotes
URL path/api/v2/ordersMost visible and common; easy to route and cache
HeaderApi-Version: 2Clean URLs; easy to forget in clients
Media typeAccept: application/vnd.shop.v2+jsonPrecise, but less familiar
Date-basedStripe-Version: 2024-06-20Each 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.

Version 1 and version 2 of an API running side by side for different clients, with a deprecation timeline for retiring the old version.
Version 1 and version 2 of an API running side by side for different clients, with a deprecation timeline for retiring the old version.

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.