Versioning and Change

The scanner app in an organizer's pocket was installed eight months ago and will not be updated tonight. The web client was deployed this morning, the mobile app is on three versions across its users, and a partner's integration was written once by a contractor who has left. Every change to the API is made against clients that will not change with it. The first rule follows from that: most changes must not need a version at all. The second follows from the first: a version, when it is finally needed, is a promise about how long the old one lives, and a promise with no date is not one.

Stagedoor has never shipped a v2 and this topic explains what it does instead. Additive changes ship without ceremony, because the contract obliges clients to ignore what they do not know. Breaking changes are rare, and when one is unavoidable it is made as an expansion followed by a contraction, with a header that says the old surface is deprecated, a header that says when it goes, and a count of who is still calling it before the day arrives.

Additive Change Needs No Version

A new optional field in a response, a new endpoint, a new enum value, a new query parameter with a default that preserves the old behaviour: each one leaves every existing client correct. The client that does not know held_until does not read it. The client that does not know partially_refunded treats it as "other," because Topic 13 made that a requirement of the contract. The client that never sends the new parameter gets the default, which is what it got before. Stagedoor ships an additive change most weeks, and none of them has a version, an announcement or a sunset, because nothing that worked yesterday stops working.

The contract does its half of the work. "Clients must ignore unknown fields and tolerate unknown enum values" is a sentence in the API document, and it is there for exactly this reason: it converts a whole class of changes from breaking to additive, before any of them is made. A client that fails on an unknown field has broken the contract, and the fix is on the client's side, which is the only time the service gets to say that.

Breaking Change, Defined

Removing a field. Renaming a field. Changing a field's type. Tightening validation, so that a value that was accepted is now rejected. Changing a status code, so that a client's branch on 409 now sees 422. Changing the meaning of a value while keeping its name. Each one breaks a client that was correct yesterday, and the list is the definition of "needs a version." Nothing else does. A team that keeps the list in front of it makes fewer breaking changes than a team that reasons case by case, because most proposed changes turn out to have an additive spelling: a new field beside the old one instead of a rename, a wider validation instead of a tighter one, a new endpoint instead of a changed response.

Where the Version Goes

Three places. In the path, /v2/orders: visible in every URL, coarse, and it turns every breaking change into a copy of the whole API. In the media type, through content negotiation: precise and almost nobody's client sends it correctly. In a header, Stagedoor-Version: 2026-10-01: the version is a date, the date is the day the client was written against, and a client pins the day it was tested on and sees the API as it was that day for as long as the sunset allows. Stripe has done this since 2011, and it is what Stagedoor does.

The part that makes a date header workable is where the translation happens. The handlers are written once, against the current shape. A routing layer reads the version header and applies the translations for every dated change after the client's date: rename this field back, re-add that removed one, map the new status code to the old. Each dated change is a small function, and a client from eight months ago passes through eight months of them. Handlers never see the version. The alternative, a handler per version, is how /v7/ happens.

Expand, Then Contract

To rename starts_at to begins_at: add begins_at beside it and emit both. Migrate the clients the team controls. Mark starts_at deprecated with the headers of the next section. Watch the per-client counter until the callers that read it are gone or have been told. Then remove it, after the sunset. Five steps, and at no point does a correct client see a response it cannot read. The shape is the same as the schema migration of Chapter 6, add the column, backfill, switch the readers, drop the old column, and it is the same for the same reason: two versions of the reader exist at once, and the writer has to satisfy both until the old one is gone.

The step people skip is the middle. A rename that adds the new name and drops the old one in the same release has expanded and contracted at once, which is a rename in place, which is the breaking change. The expansion has to live long enough for the slowest client to move, and the slowest client is the scanner app, and its release cycle is the sunset's lower bound.

Deprecation Is a Header and a Date

Every response from a deprecated surface carries two headers. Deprecation, from RFC 9745, says that the surface is deprecated and since when, as a Unix timestamp with an at-sign in front. Sunset, from RFC 8594, says the date after which it will stop responding, as an HTTP date. A client library that knows the headers logs a warning on the first one; a client that does not is at least visible, because the service logs every request that hit a deprecated surface with the client's identity, and the count per client is the number the sunset is decided on.

HTTP/1.1 200 OK
Stagedoor-Version: 2026-02-14
Deprecation: @1790812800                       # deprecated since 2026-10-01T00:00:00Z
Sunset: Sun, 01 Nov 2026 00:00:00 GMT          # gone after this instant
Link: <https://stagedoor.example/docs/changes/begins-at>; rel="deprecation"

{ "id": "8812", "starts_at": "2026-10-04T19:30:00Z", "begins_at": "2026-10-04T19:30:00Z", ... }

The response is pinned to a client date from February, so it still carries starts_at, and it carries begins_at beside it because the expansion is in effect. The Deprecation header says the old field has been deprecated since the first of October, the Sunset header says it stops on the first of November, and the Link header points at the page that says what to do. A sunset without a measured caller count is a guess; the header is the promise and the counter is what makes the promise keepable.

The Client That Never Updates

The scanner app is pinned to the version it shipped with, and the service serves that version until the sunset. The sunset is set longer than the app's release cycle, which for a mobile app in organizers' pockets is three months from store release to the last device updating, so a sunset shorter than that is a sunset the team will extend under pressure. On the day the old version goes, a request pinned to it gets a 410 Gone with a Problem Details body whose type is problems/version-retired and whose extension points at the update. The app shows "update required" instead of an undated event list, which is what a silently renamed field would have given it.