Versioning: Why /v1 Is in the URL

Tandem's partner newsletter announces version 2 of the API. Among the changes: the field free_bikes becomes available_bikes. It is a better name — it says what the number counts without implying the bikes are free of charge — and if it went live at the address Vera calls, every report in Riverport built on that field would break on a Tuesday morning with no warning.

It will not, and the reason is the two characters you have typed on faith since Chapter 2. The /v1 in api.tandem.example/v1 is a version: a label on one particular edition of the promise. Versions are how an API changes without breaking the people who depend on it.

The Promise Problem

Chapter 1 defined an API as a promise written down: send this shape of request, receive that shape of answer. The trouble is that promises live in time. Tandem's engineers learn things, add features, and want to correct names they regret — and every one of those improvements is a chance to invalidate what somebody already built.

Two things must be true at once. The provider has to be able to change the API, or it slowly becomes useless. The consumer has to be able to not wake up broken. Versions resolve that: the old promise keeps being kept at the old address while the new one opens next door, and the consumer chooses when to walk over.

The everyday version is a bank changing a form. The new form has a renamed field and a better layout, and for a posted transition period the branch accepts both. Nobody's mortgage collapses because a box was relabelled, and nobody is turned away at the counter for holding last year's paper. What makes that civilized is not the new form. It is the posted period.

Where Versions Live

Tandem puts the version in the path, which is the most visible option and the most common one you will meet: /v1/stations and /v2/stations are two addresses, and which one you get is decided by what you typed.

Other APIs put it elsewhere. Some take a header naming the version, sometimes a dated one. Some take a query parameter. The mechanism differs; the meaning does not, and the documentation always says which edition it is describing. That is the complete explanation of the version selector Chapter 6 warned you about: a docs site can show you v1 while your URL says v2, and then the page and the wire disagree for a reason that has nothing to do with anyone being wrong.

It also closes the small mystery that chapter left open. A field named on a reference page that the response does not contain is exactly what a rename in progress looks like from below — the page and the endpoint describing two different moments of the same promise. Renaming is precisely the kind of change a version boundary exists to hold, and when Tandem's rename ships it ships at /v2, leaving free_bikes untouched at /v1.

Breaking and Non-Breaking Changes

Not every change needs a new version, and the dividing line is simple enough to hold in your head. A change is breaking if a consumer doing exactly what it did yesterday now gets something it cannot use: a field renamed, a field removed, a value that changes type, an endpoint retired. Those wait for a new version.

Adding, on the other hand, breaks nobody. If Tandem starts including a last_serviced field on every station tomorrow, Vera's report neither notices nor cares — it reads the fields it came for and lets the rest be. That is why Chapter 4 taught the habit of letting unfamiliar fields exist rather than treating them as errors. The reader has been version-tolerant since then without being told, and it is the single habit that makes additive change safe for everybody.

The Consumer's Calendar

When a version is eventually retired, that is announced rather than sprung. The provider publishes a deprecation notice — this edition is on its way out — along with a sunset date, the day it stops answering. Both usually arrive by email and in the changelog, and some APIs go further and attach a literal Sunset header to responses from the old version, so the warning rides along with the data itself. Alongside them comes a migration guide, which for a rename is often a plain table of old names against new.

Vera's move is unhurried, and it is the whole point of the mechanism. She reads the changelog when the newsletter arrives. She checks which fields her report touches. She tries v2 against the sandbox with her test key, sees available_bikes where free_bikes used to be, adjusts the two places her spreadsheet names that field, and then changes the version in the URL. Weeks of calm, done at her own pace, instead of a morning of mystery.