Member-only story
API Versioning Without Breaking Old Clients
How to evolve an API safely with additive changes, tolerant readers, compatibility tests, and a deprecation process that gives consumers time to move.
An API can be healthy, fast, and fully available — and still break production.
Imagine a mobile app that has been installed on a customer’s phone for months. Your backend team ships a cleaner response model on Friday. The new web client works perfectly. The old mobile app, which has not been updated, starts failing because a field it expects has disappeared. There is no server outage. CPU and latency look normal. Yet customers cannot complete a core workflow.
This is the hidden cost of changing an API: the server is not the only software that depends on the contract.
The scenario above is hypothetical, but the compatibility problem is real and common. Public APIs, mobile clients, partner integrations, internal services, webhook consumers, and SDKs can all upgrade on different schedules. The producer may deploy in minutes; some consumers may take weeks or may never upgrade at all.
API versioning is often presented as a choice between /v1 and /v2. That is only one part of the design. The harder work is defining what counts as a breaking change, making safe changes by default, finding every consumer that still depends on old behavior, and retiring a contract without creating an outage.
