Breaking change (API)
An API breaking change is a modification that causes existing clients — written against the previous API version — to fail, produce incorrect results, or require code changes to continue functioning. Common breaking changes: removing a field from a response, changing a field's data type, renaming an endpoint, making a previously optional request parameter required, changing authentication requirements, or altering error response semantics.
Why it matters in practice
Breaking changes are the primary source of production incidents in API evolution. A field removal that seems harmless to the provider can cause parsing exceptions in hundreds of client applications. The key principle is that breaking changes are not about the magnitude of the change — they are about the impact on existing consumers. Even a "small" change like renaming a JSON field from user_id to userId breaks every existing client that references user_id.
Common mistakes
- •Assuming clients are "robust" and will handle missing fields gracefully — many production clients fail hard on missing expected fields.
- •Not documenting breaking changes in migration guides — consumers need step-by-step instructions, not just a changelog.
- •Making breaking changes without a deprecation period — sudden changes break production systems; deprecation allows planned migration.
Related Terms
Semantic Versioning (SemVer)
MAJOR.MINOR.PATCH scheme communicating compatibility changes.
Major, minor, and patch bumps (API)
Patch fixes bugs, Minor adds features, Major breaks compatibility.
URL versioning vs header versioning
URL embeds version in path; header uses custom headers.
Consumer-driven contracts
Consumers define expectations; provider runs contracts as tests.