An API that works well on the server side but breaks its clients on every release is not a reliable API, no matter how clean the code behind it is. The real issue is almost never the endpoint itself: it's the absence of an explicit contract about what can change without notice and what cannot. This post lays out concrete rules for evolving a REST API (and, to a lesser extent, GraphQL) without turning every deployment into a potential incident for consumers.

The problem: compatibility is never written down

In most projects, there is no shared definition of what counts as a breaking change. A developer adds a required field to a request payload, renames a JSON key to make it clearer, or changes a date format from "2025-12-01" to a Unix timestamp, treating each as an implementation detail. On the client side, these are production outages.

The typical symptom: a fix shipped on a Friday silently breaks a mobile client that hasn't updated yet, because the status field that used to be "active" is now "ACTIVE". No API version changed. Nobody was warned.

Why it happens: the API as an implicit interface

A REST API is a contract, in the same sense as a public function signature in a library. The problem is that this contract is rarely formalized beyond an OpenAPI schema generated after the fact, documenting the current state without ever committing to its future stability.

Three categories of change are consistently underestimated:

  • Structural changes: renaming a field, changing its type (string to number), switching from an object to an array.
  • Semantic changes: the field keeps its name and type, but its meaning shifts (a total that used to include tax suddenly doesn't).
  • Behavioral changes: a different HTTP status code for the same error case, a sort order that changes, pagination moving from offset-based to cursor-based.

The last two categories are the most dangerous because they don't break anything at the schema or type-validation level: everything still "works," but the client makes wrong decisions on perfectly well-formed data.

Diagnosing it: trace who consumes what

Before changing anything, you need to know who consumes the API and how. Without that visibility, every change is a gamble.

// Express middleware to log real usage per client
function trackApiUsage(req, res, next) {
  const clientId = req.headers['x-client-id'] ?? 'unknown';
  const apiVersion = req.headers['x-api-version'] ?? 'unversioned';

  metrics.increment('api.request', {
    route: req.route?.path ?? req.path,
    method: req.method,
    clientId,
    apiVersion,
  });

  next();
}

With a few weeks of aggregated metrics, concrete questions get answered: which clients are still on v1, which endpoints are actually called in production (many are rarely used), and which response fields are actually read client-side (hard to know server-side, but a grep through consumer code, when accessible, gives a good signal).

The fix: explicit compatibility rules

Version the contract, not the code

Versioning in the URL (/v1/orders, /v2/orders) or in a header (Accept: application/vnd.myapi.v2+json) exists to isolate breaking changes, not to version every micro-evolution. The baseline rule, popularized by Stripe and most mature APIs, still holds: within a major version, only additive changes are allowed.

Non-breaking changes (safe within a version):

  • adding a new optional field to a response,
  • adding a new endpoint,
  • adding a new possible value to an enum, provided clients are contractually required to handle unknown values with a sensible default.

Breaking changes (require a new version or a deprecation window):

  • removing or renaming a field,
  • making a previously optional field required,
  • changing the type or format of an existing field,
  • changing the HTTP status code of an existing response.

Formalize the contract with a versioned, tested schema

An OpenAPI or JSON schema only has value if it's tested in CI against real responses, not merely generated as static documentation.

# openapi.yaml - excerpt, with an additive field and an explicitly deprecated one
components:
  schemas:
    Order:
      type: object
      required: [id, status, totalAmount]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, confirmed, shipped, cancelled]
        totalAmount:
          type: number
          description: "Total amount including tax, in cents."
        legacyTotal:
          type: number
          deprecated: true
          description: "Deprecated since v2.3, removed in v3. Use totalAmount."
// Contract test: verifies no required field has disappeared
// and deprecated fields are still present until the sunset date
import { validateAgainstSchema } from './schema-validator.js';
import ordersResponseV2 from './fixtures/orders-v2-response.json';

test('the /v2/orders response honors the published contract', () => {
  const result = validateAgainstSchema(ordersResponseV2, 'Order');
  expect(result.missingRequiredFields).toEqual([]);
  expect(result.deprecatedFieldsRemoved).toEqual([]);
});

Progressive deprecation, never a hard cutoff

The healthy cycle for removing a field or an endpoint: announce the deprecation (Deprecation and Sunset headers per RFC 8594, documentation, outreach to known integrators), leave a realistic window (weeks to months depending on the client base), confirm via usage metrics that traffic on the old field drops to zero, and only then remove it.

app.get('/v2/orders/:id', (req, res) => {
  const order = getOrder(req.params.id);

  res.set('Deprecation', 'true');
  res.set('Sunset', 'Wed, 01 Apr 2026 00:00:00 GMT');
  res.set('Link', '</docs/migration/orders-v3>; rel="deprecation"');

  res.json({
    ...order,
    legacyTotal: order.totalAmount, // duplicated field during the transition
  });
});

Automating compatibility checks in CI

Relying on reviewers to manually spot a breaking change in a pull request doesn't scale once an API has more than a handful of endpoints. The schema diff itself can be checked automatically, failing the build before a breaking change ever reaches a staging environment.

# CI step: diff the current OpenAPI schema against the one published in production,
# failing the build on any breaking change
npx oasdiff breaking openapi-production.yaml openapi-current.yaml --fail-on ERR

A tool like oasdiff (or openapi-diff) classifies changes into breaking and non-breaking categories based on the same rules outlined above: a removed required-response field is breaking, an added optional field is not. Wiring this into the pull request pipeline turns the compatibility rule from a convention people are expected to remember into a gate that physically blocks the merge.

# .github/workflows/api-contract.yml - excerpt
- name: Check API backward compatibility
  run: |
    curl -o openapi-production.yaml https://api.example.com/openapi.yaml
    npx oasdiff breaking openapi-production.yaml ./openapi-current.yaml --fail-on ERR

This doesn't replace contract tests against real response payloads (a schema can technically stay compatible while the server returns something that violates it), but it catches the majority of accidental breaking changes at the cheapest possible point: before a reviewer even opens the diff.

Communicating changes to consumers who aren't watching a changelog

Even a perfectly backward-compatible change can still surprise a consumer if a new optional field changes how they should be interpreting the response (a new discountedTotal field that coexists with totalAmount but represents the number most clients should now display). Technical non-breaking status and practical safety for the client are not the same thing.

For APIs with external integrators, a changelog endpoint or a webhook on schema changes gives consumers a way to react proactively instead of discovering a new field by diffing responses:

// Webhook fired whenever the published OpenAPI schema changes,
// letting registered integrators pull the diff and decide whether to adapt
async function notifySchemaChange(diff) {
  const subscribers = await getWebhookSubscribers('schema.updated');
  await Promise.all(
    subscribers.map((sub) =>
      fetch(sub.webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ event: 'schema.updated', diff, version: 'v2' }),
      })
    )
  );
}

For an internal API consumed only by teams within the same organization, a simple Slack notification tied to the same CI check is usually enough; the point is that the notification path exists at all, rather than depending on someone remembering to update a wiki page.

The tradeoffs

Maintaining several versions in parallel has a real cost: duplicated logic, multiplied test suites, confusion for newcomers about which version to touch. The temptation to "clean up" by breaking everything at once is strong, but it shifts the cost onto clients, who don't always control their own update schedule (mobile apps with old versions still installed on devices that never auto-update, third-party integrations owned by other teams).

A pragmatic alternative is compatibility-by-transformation at the boundary: keep a single internal data model, and adapt the exposed shape based on the requested version in a dedicated serialization layer, rather than duplicating business logic.

When the "simple" version isn't enough

Bumping the version on every minor change produces the opposite of the intended effect: clients get no stability guarantee at all and end up migrating constantly. If an API changes so often that URL-based versioning becomes unmanageable, the real problem is probably insufficient stabilization of the data model upstream, not a lack of versioning tooling.

For internal APIs with tight coupling (microservices owned by the same team), strict versioning is sometimes a disproportionate cost: a shared contract with consumer-driven contract tests (Pact-style) can be enough without multiplying URL versions.

The point to keep: backward compatibility isn't a constraint you suffer after the fact, it's a discipline you code into the system - versioned schema, contract tests in CI, standard deprecation headers. Without that, every deployment is back to being a bet on what clients won't notice.