A precise definition
A change is breaking if there exists a reasonable client that worked against the old version and does not work, or silently does the wrong thing, against the new one. That second half matters: many of the most expensive breaking changes never throw an error.
It helps to split breaking changes into two families:
- Contract breaks change the shape of the API: a field disappears, a type changes, a required parameter is added. Tools that compare specifications can usually catch these.
- Behavioral breaks keep the shape and change the meaning: an amount switches from dollars to cents, a list changes its default sort order, an enum value is retired. The schema is identical; the client is now wrong.
12 common examples
- Removing an endpoint, method or field.
- Renaming a field, for example
customertocustomer_id. - Changing a field type, such as
total: numberbecomingtotal: { amount, currency }. - Making an optional request parameter required.
- Removing or renaming an enum value that clients compare against.
- Adding a new enum value to a response when clients switch over it exhaustively.
- Changing units or precision, such as major to minor currency units.
- Changing a default: page size, sort order, time zone, or included fields.
- Changing status codes or error formats that clients branch on.
- Tightening validation, such as shorter maximum lengths or stricter formats.
- Changing authentication or required scopes.
- Lowering rate limits or changing pagination semantics.
By contrast, adding a new endpoint, adding an optional request parameter, or adding a response field is usually safe, as long as clients ignore fields they do not recognise. "Usually" is doing real work there: a client that validates responses strictly can break on an added field.
Why your test suite misses them
Unit and integration tests check the behavior you thought to test. Three things make breaking changes slip through:
- Mocks freeze the past. Client tests often run against recorded or hand-written responses, so they keep passing against the old behavior long after the real API has moved.
- Semantic changes keep the shape. A unit change from dollars to cents passes every type check and every schema validation.
- Coverage is not usage. The call paths your customers rely on in production are rarely the ones your tests exercise most.
This is why “all tests pass” is a weak signal for API migrations, and why a passing build is not the same as proof that behavior didn't change.
How to detect breaking changes
Mature teams layer three techniques:
- Specification diffing in CI. Compare the OpenAPI document on a branch against the one on main and fail the build on breaking differences. See OpenAPI diff.
- Consumer-driven contract tests. Consumers publish the interactions they rely on; providers verify every change against them. See contract testing.
- Behavioral verification. Replay real requests against the old and new versions and compare full responses. This is the only layer that catches semantic breaks. See traffic replay testing.
How to prevent them from hurting customers
You cannot avoid every breaking change; APIs have to evolve. You can control the blast radius:
- Version deliberately and let clients pin a version. See API versioning strategies.
- Announce changes with
DeprecationandSunsetheaders and a migration guide. See how to deprecate an API. - Measure who still calls the old behavior before you remove it.
- Give consumers the migration, not just the notice: codemods, updated SDKs, or pull requests against their code.
Releo is built for that last step: it finds every affected call site, writes the patch, and proves with replayed traffic that behavior did not change before the PR can merge.
Frequently asked questions
Is adding a field to an API response a breaking change?
Usually not, because well-behaved clients ignore unknown fields. It becomes breaking for clients that validate responses strictly or deserialize into closed types that reject unexpected properties.
Is adding a new enum value a breaking change?
It can be. Clients that switch over every known value, or that fail on unrecognised values, will break when a new value appears in a response. Document whether clients must tolerate unknown enum values.
What is the difference between a breaking change and a deprecation?
A deprecation is an announcement that something will be removed or changed in the future; it still works today. The breaking change happens when that removal or change actually ships, ideally after a published sunset date.