API Backward Compatibility and Breaking Changes
On this page
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
statusas "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:
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.
Retiring a field: Deprecation and Sunset headers
Replacing fullName with separate firstName and lastName:
- Add
firstNameandlastName; keep returningfullName. - Document
fullNameas deprecated, with a migration guide and a removal date. - Signal it in responses with standard headers. From a tested Express endpoint:
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.
- Measure usage: log which clients (API keys or app versions) still read the old field or call the old endpoint.
- Contact the remaining clients directly.
- 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.