# When You Must Version an API — Routebase

> The changes that have no additive path, the consumer situations that leave you no choice, and the semantic breaks that never show up in a diff.

Canonical page: https://routebase.dev/guides/api-versioning/when-to-version-an-api/
Chapter 4 of 12 · API Versioning · Last reviewed 2026-09-13 · The Routebase Team

The interesting question is not which changes are breaking, since [that classification](/guides/api-versioning/api-breaking-changes/) is a closed list. The interesting question is which breaking changes leave you no way out except a new version.

Two things decide it. What the change is, and who is on the other end.

## Changes with no additive path

Most breaking changes have an additive alternative if you look for one, which is the subject of [backward compatible change](/guides/api-versioning/backward-compatible-api-changes/). A few genuinely do not.

**A resource is being reshaped, not extended.** Splitting one endpoint into three, flattening a nested structure and moving from a single object to a collection are all the same kind of change. The old shape and the new one cannot coexist under one name. You can serve both shapes under different names for a while, and at some point that is just a version with extra steps.

**A field's type has to change.** An identifier that outgrows a 32-bit integer, a decimal amount that has to become a string for precision, a timestamp that gains a time zone. Adding a parallel field is the additive route, and it works until you have five parallel fields and no consumer knows which is authoritative.

**An input becomes mandatory.** Once an operation cannot be performed correctly without a piece of information, there is no compatible way to demand it. You can default it, and a wrong default is worse than a version.

**The meaning of a value changes.** This is the one that produces real incidents, because the shape does not move. An `amount` in cents that becomes an `amount` in whole units passes every schema check and every contract test, while consumers compute totals that are wrong by a factor of a hundred. Semantic changes are always breaking and always invisible, so they have to be declared.

**Authentication or authorization changes.** Adding auth to a previously open endpoint, replacing one scheme with another, or requiring a scope that existing tokens do not carry all break every current caller. None of them shows up in a response schema diff.

## Audiences that remove the choice

The same change can be routine in one setting and unacceptable in another, and the difference is whether you can reach the people affected.

_Figure: The callers of one API sorted by a single property, which is whether you can reach them before the change ships. An internal service and your own web app can be told, so a breaking change becomes a coordinated release. A partner SDK, a mobile app already installed and a caller you cannot name have no return path, and those are the ones that turn the same change into a version._

| Situation | Why a version becomes unavoidable |
|---|---|
| A public API with open signup | You do not know who is calling, so you cannot coordinate anything |
| Partner integrations under contract | The contract may name the interface, so a change is a commercial matter |
| Customers in regulated industries | Their release process is measured in quarters, and they cannot follow yours |
| Mobile or embedded clients | Old versions live in the field for years, and some of them never update |
| Anything with an SDK you did not write | A third-party client is generated against a contract and pinned to it |

The pattern behind the table is reach. If you can list every caller, phone them, and confirm the change landed, a breaking change can be a coordinated release. If you cannot, the version is the coordination mechanism.

Mobile is the case teams underestimate most. An application released two years ago is still installed on somebody's phone, it will never be updated, and it calls your API tomorrow morning. That single fact turns many otherwise minor changes into permanent commitments.

## Breaking on purpose, and doing it well

Sometimes the honest answer is that the current contract is wrong and no amount of additive patching will fix it. Cutting a major version is then the correct decision, and the work is in how you run it.

Three things separate a version people forgive from one they complain about for years. Announce it before it exists, so consumers hear about it from you and not from a failing build. Ship the old and the new side by side for long enough that a team can plan the migration into an ordinary sprint. Give the end date at the start, because [a deprecation with no sunset](/guides/api-versioning/api-deprecation-and-sunset/) never actually ends.

## The change you should decline

There is a fourth category worth naming, which is the breaking change that is not worth its cost.

Renaming a field for consistency, tidying an inconsistent plural, correcting a spelling in a JSON key, and reordering a response for readability all break consumers and buy nobody anything. They feel like housekeeping and they are paid for by every team integrating with you. Collect them, and spend them together when a genuine major change forces a version anyway.

## In Routebase

The classification decides the version rather than the other way round. When you open the release wizard, the first step compares the version you are about to release against the last published one and shows what the change actually is, so the version number follows evidence.

_Screenshot: The release step names the trade-off before the click, including how many breaking changes the consumers of that environment would receive._

The warning is specific rather than general. If the version you are promoting carries breaking changes against what the target environment runs today, the wizard says how many and reminds you that consumers on that version may break. Freezing is permanent, so the wizard also spells out the chain it is about to execute before you confirm it. The [Spec Versioning guide](https://docs.routebase.dev/versioning/) covers the three steps of a release and the receipt that follows.

## Frequently asked questions

### When should you create a new API version?

Create one when the change has no additive form and a consumer you cannot reach would be broken by it. Removing or renaming a field, changing a type, making an optional input required, changing what a value means, and replacing the authentication scheme all qualify. If you can reach every caller and confirm the change with them, a version is often avoidable even for a breaking change.

### Do internal APIs need versioning?

Usually not in the formal sense, because you can find every caller and coordinate the change. What internal APIs do need is the same classification discipline, since knowing a change is breaking is what triggers the coordination. Versioning becomes necessary internally as soon as one team cannot ship in step with another, which happens earlier than most organisations expect.

### Is changing the meaning of a field a breaking change?

Yes, and it is the most dangerous kind, because no diff and no schema validator will notice. An amount that switches from cents to whole units keeps the same type, the same name and the same position, so every automated check stays green while consumers silently compute the wrong number. Semantic changes have to be declared by the person making them.

### Does adding authentication to an endpoint require a new version?

Yes, if the endpoint was previously reachable without it, because every existing caller starts receiving 401 responses. The same applies to changing the scheme, tightening required scopes, or shortening token lifetimes below what clients were built to handle. These changes never appear in a response schema diff, so they need to be classified by hand.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.