I do not think every API change needs a new version.
In a lot of teams, versioning gets treated like a reflex. Something changes, somebody gets nervous, and the answer becomes v2. That can work, but it is also an easy way to avoid thinking about what actually changed, who depends on it, and whether the old contract still needs to hold.
For me, the question is simple: has the contract really changed, or are we just trying to make a breaking change feel cleaner?
Contract drift is the real signal
I start by looking at the shape of the contract itself.
If the API still means roughly the same thing, serves the same kind of client, and only needs additive changes, I usually do not reach for versioning. Add fields. Add endpoints. Add optional behavior. Keep the old shape working if you can.
Versioning starts to make sense when the contract has drifted far enough that keeping both meanings in one place would be confusing or dangerous.
That usually looks like:
- a field that used to mean one thing now needs a different meaning
- a response shape that no longer fits the old clients at all
- a workflow that has changed from one domain model to another
- a decision that would force old clients to guess wrong unless they change
At that point, the problem is not just implementation. It is compatibility.
Client expectations matter more than elegance
An API is not just a set of routes or methods. It is a promise to clients.
That promise might be weak or strong, but it exists either way. If external clients, mobile apps, scripts, or other services depend on a certain shape, then changing that shape has a cost. The more people depend on it, the more important the compatibility story becomes.
That is why I think versioning is partly a communication tool.
If I say v2, I am not just changing the URL or the namespace. I am telling clients that the old assumptions are no longer safe. That can be useful when the change is large enough that trying to preserve both behaviors in one contract would make the API muddy.
The mistake is using versioning to avoid making the compatibility boundary clear. A version should make the boundary easier to understand, not hide it.
Versioning is useful when the old behavior would be misleading
Sometimes the old contract is not just awkward. It is actively wrong for the new world.
Maybe the domain model changed. Maybe the workflow changed. Maybe the original response was built around an internal shape that no longer matches how the product works. If preserving the old interface would force the new API to keep carrying misleading names, weird nulls, or strange backwards rules, versioning can be the cleaner move.
I like versioning most when it lets me do one clear thing:
- keep the old behavior stable for existing clients
- design the new behavior without awkward compromises
That is better than pretending one contract can absorb everything forever.
Versioning is not a substitute for discipline
I do not like versioning as an excuse to ship sloppy changes.
If a team versions too early or too often, it usually means one of two things:
- they do not know how to evolve the API safely
- they do not want to do the work to keep the contract stable
Neither is ideal.
Good API discipline still matters. Additive change is usually better than breaking change. Clear deprecation paths matter. Changelogs matter. Good test coverage around the contract matters. If you can make a change without forcing clients to move, that is usually the better outcome.
Versioning should not be the first thing you reach for just because it feels tidy.
I think about the migration cost
The real question is not whether a new version is possible. It is whether the migration is worth it.
If the change is small, versioning often creates more work than it saves. Now you have two contracts to support, two sets of examples, two mental models, and probably some awkward code shared between them.
If the change is large enough that trying to preserve backwards compatibility would make the API hard to use or hard to explain, then versioning earns its keep.
That is the balance I try to hold:
- avoid a new version for minor evolution
- use a new version when the contract has genuinely moved
- do not let versioning become a way to postpone design decisions
What I usually want first
Before I version anything, I try a few other things first:
- add new fields instead of changing old ones
- add a new endpoint or operation instead of mutating an existing one
- keep old inputs accepted for a while if the change is mostly structural
- document the deprecation path clearly
- make sure I know which clients actually depend on the old behavior
That does not mean I avoid versioning forever. It just means I treat it as a real compatibility decision, not a default response to discomfort.
The practical answer
If the API still behaves like the same contract with a few added pieces, I usually do not version it.
If the contract has drifted enough that old clients would be misled, or the new shape would be ugly if I tried to preserve the old one, I version it and make the boundary explicit.
That is the line for me. Versioning is useful when it clarifies a real break. It is not useful when it just makes a messy change look more organized.