The cost of no versioning is paid late
The breaking change
A small change to one API response shipped on Friday. By Monday the mobile app was crashing for everyone who had not updated, and a partner integration had quietly stopped syncing.
Small teams often skip versioning entirely. It feels like overhead when the only consumer of the API is the team's own frontend. Then a mobile app is added, or a partner integration, and suddenly changing a response shape breaks something live.
The cost of adding versioning at that point, while also maintaining the old behaviour, is much higher than adding a lightweight structure at the start.
A simple prefix is usually enough
For most APIs built by small teams, a /v1/ URL prefix plus a clear policy on what constitutes a breaking change is sufficient. The policy matters as much as the structure: additions are not breaking; removals and renames are.
If the API is consumed exclusively by internal clients you control, you can also use header-based versioning and keep URLs clean. The right choice depends on who your consumers are and how much control you have over their update cadence.
| Strategy | Example | Trade-off |
|---|---|---|
| URL path | /v2/orders | Explicit and cache-friendly; best for public APIs |
| Header | API-Version: 2 | Clean URLs; good for internal clients you control |
| Query parameter | /orders?version=2 | Easy to try; easy to forget and messy to cache |
| Content negotiation | Accept: application/vnd.app.v2+json | Precise; more complex for clients |
Worried an API change will break your apps?
Get a free consultationWhat counts as a breaking change
Write this list into your API guidelines. It settles most arguments before they start.
Safe to ship
- Adding a new endpoint
- Adding an optional field to a response
- Adding an optional request parameter
- Fixing a bug without changing the contract
Needs a new version
- Removing or renaming a field
- Changing a field's type or format
- Making an optional parameter required
- Changing error codes or error shapes
Retire old versions without drama
Announce early
Tell every consumer the date, with a changelog of what changes.
Signal it in the API
Return Deprecation and Sunset headers on the old version.
Watch who still calls it
Log usage by client so you can contact the stragglers directly.
Give a real window
Months, not weeks, for mobile apps and partners.
Remove on schedule
Keep the date you announced, or nobody will believe the next one.
Frequently Asked Questions
Written by
Sachin Patel
Backend Engineering
