Breaking changes are inevitable. User schemas evolve. Response formats get rationalized. Fields get renamed for consistency. The question isn't whether your API will break clients — it's how gracefully you handle it when it does.
Most teams have this conversation too late: after an important client is already broken, two versions behind, submitting angry support tickets.
The three approaches
Path versioning (/v1/users, /v2/users) is the most common and usually the right choice for public APIs. Versions are explicit, easy to route, easy to deprecate. The downside: you end up maintaining multiple active versions simultaneously.
Header versioning (Accept: application/vnd.api+json;version=2) keeps URLs clean but makes versioning invisible in browser address bars and API documentation. Good for internal APIs where you control all consumers.
Query parameter versioning (/users?version=2) is easy to implement but easy to forget and easy to misuse. Generally the weakest choice.
What actually breaks clients
Removing or renaming fields breaks clients. Changing field types breaks clients. Changing the shape of nested objects breaks clients.
Adding new optional fields almost never breaks well-written clients. Clients should ignore fields they don't understand. If yours don't, that's a separate problem.
The spec versioning approach
Before changing a contract, version the spec. Tools like moqapi.dev store every version of your OpenAPI spec with a timestamp, let you diff between versions, and let consumers test against any version via a stable URL.
This gives you a clear record of every breaking change, when it was made, and what the shape was at any point in time. Invaluable when a client files a "you broke us" ticket three weeks after a deploy.
The practical rule
Never remove a field from a response without a deprecation period. Add new fields freely. Rename by adding the new name alongside the old one for one API version, then removing the old name in the next. Give clients at least 90 days after a deprecation notice.
Simple rules, consistently applied, prevent most versioning disasters.
Top comments (0)