Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 4 · Lesson 23 · 3 min read

API Backward Compatibility and Breaking Changes

On this page
  1. Why backward compatibility matters
  2. Safe vs breaking API changes
  3. Tolerant clients: ignore unknown fields and values
  4. Retiring a field: Deprecation and Sunset headers
  5. Catching breaking API changes in CI
  6. Check yourself

Why backward compatibility matters

Your web app updates when you deploy. Mobile apps update when users get round to it; some never do. Partner integrations change when the partner has budget. Any change you ship must work with all of those clients at once.

Safe vs breaking API changes

Changes that are safe:

  • Add new endpoints, optional request fields, and response fields.
  • Add new optional query parameters with defaults that preserve old behavior.
  • Relax validation (accept longer strings, more formats).

Changes that break:

  • Removing or renaming anything clients use.
  • Changing types, formats or units.
  • Tightening validation or making optional fields required.
  • Changing default behavior or the meaning of a value.

When you need to "rename" a field, add the new one alongside the old, populate both, and remove the old one only after clients have moved.

Tolerant clients: ignore unknown fields and values

Compatibility is a two-way agreement. Document that clients must:

  • Ignore unknown fields in responses, rather than failing strict validation.
  • Handle unknown enum values gracefully (treat a new status as "other").
  • Not depend on field order or undocumented behavior.

In code, a tolerant client looks like this. The server has added a giftWrap field and a new partially_refunded status that this client has never heard of:

JavaScript
const LABELS = { pending: 'Pending', paid: 'Paid', shipped: 'Shipped' };
const statusLabel = (order) => LABELS[order.status] ?? 'Processing';   // safe default

statusLabel({ id: 482, status: 'partially_refunded', giftWrap: true });   // "Processing"

The unknown field is simply never read, and the unknown status gets a sensible label instead of a crash. A client that validated responses against a closed list of statuses would have broken the day the server added one.

Generate SDKs that follow these rules, so most integrators get them for free.

Old and new fields coexist while clients migrate; deprecation headers warn callers, and usage tracking shows when the old field can be removed.
Old and new fields coexist while clients migrate; deprecation headers warn callers, and usage tracking shows when the old field can be removed.

Retiring a field: Deprecation and Sunset headers

Replacing fullName with separate firstName and lastName:

  1. Add firstName and lastName; keep returning fullName.
  2. Document fullName as deprecated, with a migration guide and a removal date.
  3. Signal it in responses with standard headers. From a tested Express endpoint:
YAML
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"

Deprecation (RFC 9745, 2025) gives the date the resource was deprecated as a Unix timestamp (@1798761600 is 1 January 2027). Sunset (RFC 8594) gives the date it stops working. The Link points to the migration guide. In GraphQL, use @deprecated(reason: "Use firstName and lastName") on the field.

  1. Measure usage: log which clients (API keys or app versions) still read the old field or call the old endpoint.
  2. Contact the remaining clients directly.
  3. Remove it after the sunset date, ideally after a brief "brownout" (returning errors for short scheduled periods) so stragglers notice before the final removal.

Catching breaking API changes in CI

Compare the API description in each pull request against the version in main:

  • oasdiff or openapi-diff for OpenAPI specs.
  • GraphQL Inspector or schema checks in Apollo GraphOS for GraphQL.
  • Contract tests (Pact) that run consumers' expectations against the provider.

Fail the build on breaking changes unless they're deliberately approved and versioned (Day 6).

Check yourself

Add the new field alongside the old one, return both, deprecate the old one, and remove it only after clients have migrated.

Deprecation says the endpoint or field is deprecated, and since when; Sunset gives the date after which it will stop working. Clients and monitoring can detect them automatically, and a Link header can point to migration docs.

So the provider can add fields, the most common and safest kind of change, without breaking anyone. Clients that fail on unknown fields turn every addition into a breaking change.

Treated unknown enum values as a safe default, such as "Processing", instead of assuming the list of statuses would never grow.