Versioning without breaking clients

Once an API has clients you do not control — mobile apps that users never update, partners with quarterly release cycles — every change is either safe for all of them or breaks some of them. Versioning is how you ship the second kind without breaking anyone who has not opted in.

Breaking and non-breaking

A change is breaking when a correct, existing client stops working. The usual list:

• removing or renaming a response field, or changing its type;
• adding a required request field, or making an optional one required;
• changing the meaning of a field, a status code, or a default;
• tightening validation that used to accept a value;
• removing an endpoint, a method or a request field the API would now reject.

Usually non-breaking: adding an endpoint, adding an optional request field, adding a response field. That last one is only safe if clients are tolerant readers — they ignore fields they do not know. Document that as a rule of the API, because a client that validates responses strictly turns every addition into a break:

1const KNOWN = ["id", "status"];2 3function strictClient(body) {4  const unknown = Object.keys(body).filter((k) => !KNOWN.includes(k));5  if (unknown.length) throw new Error(`unexpected field ${unknown[0]}`);6  return body.status;7}8 9function tolerantClient(body) {10  return body.status;11}12 13function attempt(client, body) {14  try {15    return client(body);16  } catch (e) {17    return `error: ${e.message}`;18  }19}20 21export function run() {22  const before = { id: "7", status: "paid" };23  const after = { id: "7", status: "paid", paidAt: "2026-03-01T09:30:00Z" };24  return {25    strict: [attempt(strictClient, before), attempt(strictClient, after)],26    tolerant: [attempt(tolerantClient, before), attempt(tolerantClient, after)],27  };28}

One trap sits in the middle: adding a value to an enum. A client with an exhaustive switch over status crashes or mislabels the new value. Tell clients up front that enums may grow, and that unknown values need a default branch.

Where the version goes

• URI path — /v1/orders, /v2/orders. Visible in every log and link, trivial to route, cache-friendly. The cost: a "version" applies to the whole API and resources get two URIs.
• Request header — a custom header such as Api-Version: 2, or a media type, Accept: application/vnd.example.v2+json. URIs stay stable and resources keep one identity, but the version is invisible in a browser and every cacheable response must carry Vary on that header.
• Query parameter — ?version=2. Easy to try out, easy to forget.
• Date-based pinning — some APIs name versions by release date and pin each client account to the version current when it started; the client upgrades by changing its pin.

1const RELEASES = ["2024-01-15", "2024-09-01", "2025-03-10"];2 3// The newest release on or before the pinned date.4function resolve(pin) {5  const eligible = RELEASES.filter((r) => r <= pin);6  return eligible.length ? eligible[eligible.length - 1] : null;7}8 9export function run() {10  return ["2024-12-01", "2025-03-10", "2023-06-30"].map((pin) => `${pin} -> ${resolve(pin)}`);11}

None of these is the standard; consistency and a deprecation policy matter more than the mechanism.

Deprecation

Version only for breaking changes, and run old and new side by side. Announce the dates in documentation and in responses. Two standard response headers exist for this: Deprecation (RFC 9745, 2025) carries the date the resource was or will be deprecated, as a structured-field date such as Deprecation: @1767225600, and Sunset (RFC 8594) carries the HTTP date after which the resource is expected to stop responding. Measure which clients still call the old version before switching it off.

Common mistakes

• Bumping the version for additive changes, so clients face a migration for nothing.
• Calling a change "non-breaking" because it only adds a required field or tightens validation.
• Header-based versions without Vary, so a cache returns a v1 body to a v2 client.
• Adding enum values without having told clients to expect them.

What interviewers ask

• Is adding a field to a response a breaking change? — not for tolerant readers, which an API should require; it is for clients that reject unknown fields.
• URI versioning or header versioning? — path is explicit, cacheable and easy to route; header keeps URIs stable but needs Vary and is less visible. Either works if it is consistent.
• How do you retire v1? — run both, announce the dates (docs, plus Deprecation and Sunset headers), track remaining callers, contact them, then switch off.