API versioning

What it is and why it exists

An API version names a stable set of externally observable behavior. That behavior includes request shapes, response shapes, status codes, relevant headers, authentication rules, defaults, ordering, and side effects. A version is therefore wider than a JSON schema and narrower than an arbitrary release of the service.

Versioning exists because an API provider and its clients rarely deploy together. If a provider changes total from a number to an object, code compiled and deployed months earlier may still read it as a number. Keeping the old contract available gives those clients a migration window while new clients adopt the replacement.

A breaking change is a change that can make a previously valid interaction fail or mean something different. Removing a field and adding a required request parameter are obvious examples. Changing a default sort order, tightening validation, or returning a new enum value can be just as disruptive even when the schema diff looks small.

Version only when compatibility cannot reasonably be preserved inside the current contract. Adding an endpoint or an optional request parameter usually fits an existing version. Adding a response field is safe only when supported clients tolerate unknown fields; compatibility is evidence about consumers, not a property inferred from the word “optional.”

API versions appear at a boundary such as /api/v1/orders, a request header, an Accept media type, or a query parameter. The identifier may be a major number or a date. Its spelling is a policy choice; the real promise is which changes can land in place and how long older contracts remain supported.

How it works

Versioning adds a selection step before normal request handling. The server resolves the requested version, rejects unsupported values, applies that version’s request rules, runs shared domain behavior, and formats the result through a version-specific presenter. Keeping selection and presentation at the edge prevents the domain model from splitting into one copy per public contract.

The public API contract is the unit that gets versioned. Database schemas, internal event formats, and deployment versions may evolve on separate schedules. Exposing those internal versions directly couples clients to changes they do not need to see.

Draw the compatibility boundary

Before assigning a new version, write down the previous promise and the proposed promise. Compare the whole exchange, not only property names. A useful inventory covers:

• method, target URI, query parameters, and request headers;
• request media type, body shape, validation, and defaults;
• response status, headers, media type, body shape, and ordering;
• authentication, authorization, idempotency, and other side effects.

Then classify the change from the consumer’s direction. A server that accepts an additional optional request field has widened its input. A server that stops accepting a formerly valid value has narrowed it and can break an old client. For responses, the provider produces data, so removing an established value is the usual breaking direction.

Choose one visible selector

Path versioning gives each major contract a distinct URI, such as /api/v1/orders. It is easy to inspect, route, log, and cache. The cost is that resource identifiers change across versions, so links and client configuration must change during migration.

Header versioning keeps the target URI stable. A vendor media type in Accept uses HTTP content negotiation ; a service-specific header is another explicit selector. If a cacheable response changes according to Accept or a custom version header, the response needs the corresponding Vary field so a cache does not reuse one version for another request.

A query selector such as ?api-version=2027-01-01 is visible and usually participates in a cache key because it is part of the target URI. It can, however, be mistaken for an ordinary filter and omitted by generated clients. Whichever scheme you choose, define the behavior for missing, malformed, unsupported, deprecated, and retired values.

Do not accept several selectors without a precedence rule. If /v1/orders and X-API-Version: v2 appear together, guessing hides client bugs. Reject the conflict or document one authoritative selector and test that rule.

Separate API versions from releases

Many teams expose only a major identifier while deploying minor fixes and compatible additions in place. Google APIs, for example, document major versions such as v1 rather than exposing minor and patch numbers in their REST paths. This resembles Semantic Versioning, but it is an API compatibility policy, not proof that every service release follows SemVer.

A date identifier names a compatibility snapshot, not necessarily the date of every deployment. It works well when consumers want an explicit behavior cutoff. Major numbers work well when the migration is understood as a named contract generation. Neither scheme tells clients anything useful unless the changelog and support policy define the difference.

Run versions through a lifecycle

A production lifecycle normally has supported, deprecated, and retired states. Deprecation warns clients to migrate but does not itself change how the resource behaves. Retirement ends the compatibility promise and may produce 410 Gone, another documented response, or removal at the routing layer.

Track usage by authenticated client or another stable integration identifier before choosing a retirement date. Raw request counts are not enough: one low-volume payroll or settlement job can matter more than millions of test calls. Publish a migration guide, observe migrations, contact remaining owners, and remove a version only after the stated policy permits it.

Examples

Route at the boundary

This example exposes two path versions over one stored order. The version-specific code only selects and formats the public representation; it does not copy the order lookup or business rules.

The v1 presenter preserves a numeric total. The v2 presenter can introduce an amount and currency object without making v1 clients parse a new type. The unknown version fails explicitly instead of falling through to whichever implementation happens to be current.

Real services should select the version before expensive work and keep version routers thin. If business behavior truly differs between versions, name that policy explicitly and test it at the domain boundary rather than burying it in serializers.

Test compatibility against client behavior

An additive response field often works, but a strict generated decoder may reject it. This small experiment runs the same three responses through a tolerant client and a strict client.

const cases = [
  ["original", { id: "ord-7", total: 25.99 }],
  ["additive", { id: "ord-7", total: 25.99, receiptUrl: "/receipts/r-9" }],
  ["breaking", { id: "ord-7", total: { amount: "25.99", currency: "USD" } }],
];

function tolerantClient(body) {
  if (typeof body.id !== "string") throw new Error("id must be a string");
  if (typeof body.total !== "number") throw new Error("total must be a number");
  return body.id;
}

function strictClient(body) {
  const allowed = new Set(["id", "total"]);
  if (Object.keys(body).some((name) => !allowed.has(name))) {
    throw new Error("unknown field");
  }
  return tolerantClient(body);
}

for (const [name, body] of cases) {
  for (const [clientName, read] of [
    ["tolerant", tolerantClient],
    ["strict", strictClient],
  ]) {
    try {
      console.log(`${name} / ${clientName}: OK (${read(body)})`);
    } catch (error) {
      console.log(`${name} / ${clientName}: ${error.message}`);
    }
  }
}

original / tolerant: OK (ord-7)
original / strict: OK (ord-7)
additive / tolerant: OK (ord-7)
additive / strict: unknown field
breaking / tolerant: total must be a number
breaking / strict: total must be a number

The extra receiptUrl is compatible with the tolerant reader and incompatible with the strict one. That is why a schema-diff tool can flag likely risk but cannot deliver the final verdict. Generated SDK settings, recorded consumer contracts, and traffic evidence complete the picture.

Do not respond by promising never to add fields. Define an extensible response policy, configure official SDKs to tolerate unknown fields where the format permits it, and test representative consumers before relying on additive evolution.

Generate standard deprecation signals

RFC 9745 defines Deprecation as a Structured Field Date, written as @ followed by Unix seconds. Sunset uses an HTTP date and announces when the resource is expected to become unresponsive. The two dates have different formats.

function lifecycleHeaders(deprecationAt, sunsetAt, guideUrl) {
  if (sunsetAt < deprecationAt) {
    throw new Error("sunset must not precede deprecation");
  }

  return {
    Deprecation: `@${Math.floor(deprecationAt.getTime() / 1000)}`,
    Sunset: sunsetAt.toUTCString(),
    Link: `<${guideUrl}>; rel="deprecation"; type="text/html"`,
  };
}

const headers = lifecycleHeaders(
  new Date("2027-01-01T00:00:00Z"),
  new Date("2027-07-01T00:00:00Z"),
  "https://api.example.com/migrations/v1",
);

for (const [name, value] of Object.entries(headers)) {
  console.log(`${name}: ${value}`);
}

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.example.com/migrations/v1>; rel="deprecation"; type="text/html"

The deprecation link points to policy or migration documentation. These headers are hints for the resource in the response unless the service documents a broader scope. They complement direct owner notifications and a changelog; many clients never inspect lifecycle headers.

Do not emit Deprecation: true, invent Deprecation-Date, or format both dates alike. Those forms occur in older examples but do not match RFC 9745. Also keep the resource working as documented during deprecation: a warning is not permission to degrade the old contract.

Lock each supported contract with tests

Version tests should assert shared invariants and version-specific shapes. The following checks make accidental leakage between the two presenters visible.

import assert from "node:assert/strict";

const responses = {
  v1: { status: 200, body: { id: "ord-7", total: 25.99 } },
  v2: {
    status: 200,
    body: { id: "ord-7", total: { amount: "25.99", currency: "USD" } },
  },
};

function verifyShared(response) {
  assert.equal(response.status, 200);
  assert.equal(response.body.id, "ord-7");
}

verifyShared(responses.v1);
assert.deepEqual(Object.keys(responses.v1.body).sort(), ["id", "total"]);
assert.equal(typeof responses.v1.body.total, "number");

verifyShared(responses.v2);
assert.deepEqual(Object.keys(responses.v2.body.total).sort(), ["amount", "currency"]);
assert.equal(responses.v2.body.total.currency, "USD");

assert.notDeepEqual(responses.v1.body, responses.v2.body);
console.log("v1 contract: OK");
console.log("v2 contract: OK");

v1 contract: OK
v2 contract: OK

Shape checks are only one layer. Run the same assertions against the deployed HTTP boundary so routing, serialization, status codes, headers, and middleware are included. Add consumer-driven contract tests where named clients depend on behavior that a general interface description does not capture.

Keep a test suite for every supported version, not only the newest one. A refactor in shared code is exactly where old behavior can change accidentally, so the oldest supported contract needs the same release gate as the current contract.

Pitfalls

Fix: require an explicit version, or freeze the default to a documented compatibility version for its entire support window. Treat a default change as a migration event, measure unversioned traffic, and announce it like any other breaking change.

Fix: define a compatibility policy for observable API behavior. Keep build or deployment identifiers separate, expose only the granularity clients can act on, and use contract evidence to decide whether a new public version is required.

Fix: send Vary with every request field that influences representation selection and verify the effective cache key at the CDN or gateway. Vary does not make a response cacheable by itself; the normal cache controls still apply.

Fix: share domain operations and isolate unavoidable differences in request adapters and response presenters. When semantics truly diverge, make the policy branch explicit and add tests for both paths instead of duplicating the whole stack.

Fix: inventory consumers, record usage per stable client identity, publish a version-to-version migration map, and alert owners through more than response headers. Keep a rollback plan for retirement and verify that traffic has moved rather than merely declined.

In the AI era

Use an agent to carry an API change across the server and its actual consumers. For example, ask it to determine whether adding a response field is compatible with the project’s generated clients, test the proposed change against their decoders, and update a representative caller. Published schemas and consumer tests give this task a concrete starting point; the agent can discover routing and serialization details in the repository. Its result can support an in-place change, a new API version, or a staged client migration, with code and migration documentation updated together.

Further reading

• RFC 9745: The Deprecation HTTP Response Header Field
• RFC 8594: The Sunset HTTP Header Field
• RFC 9110: Vary
• Google AIP-185: API Versioning
• Semantic Versioning 2.0.0