Breaking vs non-breaking API changes

A breaking change can make an existing consumer fail without changing its code. Classification must consider request direction, response direction, and how real clients validate data.

Clearly breaking changes

Removing a path, HTTP method, parameter, response status used by clients, or schema property is usually breaking. Making an optional request field required forces existing callers to send new data. Narrowing an accepted enum, number range, string pattern, or request content type rejects inputs that were valid before.

Changing a property type is also dangerous. A string identifier becoming an integer may look cleaner to the server but breaks generated models and stored values. Moving authentication from optional to required, changing a security scheme, or removing a server URL can stop every request before business logic runs.

Usually additive changes

Adding an optional request field, a new operation, or a new response status can be non-breaking when clients ignore what they do not use. Expanding an accepted request enum or range is generally safe for the server side. Adding documentation, examples, descriptions, and deprecation markers does not change the wire contract.

“Additive” is not a guarantee. A strict response deserializer may reject unknown properties. A generated enum can fail when the server returns a newly added value. A client with exhaustive status handling may treat a new response code as an error. Classify these as potentially breaking when consumer behavior is unknown.

Direction matters

For requests, widening what the server accepts is safer and narrowing is riskier. For responses, the perspective reverses: the server producing a new shape may exceed what an old client accepts. An automated diff should therefore understand whether a schema is used for input, output, or both instead of applying one rule everywhere.

Behavior can break without a schema diff

OpenAPI comparison cannot detect every compatibility problem. Changed pagination order, different rate limits, new authorization policy, altered default values, slower timeouts, or different case sensitivity can break consumers while the document remains structurally identical. Pair contract diffing with integration tests and release notes.

A practical review policy

1. Validate both old and new documents.
2. Generate a directional contract diff.
3. Fail CI for confirmed breaking changes.
4. Require review for potentially breaking additions.
5. Test representative clients before rollout.
6. Deprecate and communicate before removal.

API Guard is designed to monitor OpenAPI changes and surface severity before a changed contract reaches consumers.

Frequently Asked Questions

Related Tools and Guides