What Constitutes an API Breaking Change?
An API change is breaking when it causes previously working client applications to fail without modifying their client code. Common examples include deleting existing endpoints, making optional parameters required, removing response fields, changing primitive data types, and tightening validation constraints.
Semantic Analysis vs Text Diffs
Line-by-line text diffs cannot understand API semantics. Reordering YAML keys or renaming descriptions appears as changes in git, while critical wire-breaking modifications three levels deep in a schema may be overlooked. Semantic contract diffing parses OpenAPI specifications into AST models and evaluates directional rules.
Automating Contract Reviews in CI
Integrating automated OpenAPI diffing into pull request workflows prevents accidental breaking changes from reaching production. Catching contract mismatches early protects third-party integrators and mobile app clients from unexpected outages.