How to detect breaking API changes in a pull request

What counts as a breaking change#

A breaking API change is any edit that makes an existing caller fail or behave differently. Most teams learn about one after a deploy. Two review steps catch many of them earlier: diff the contract, then check who calls what changed.

• Removing or renaming an endpoint or path.
• Removing a response field or changing its type.
• Adding a required request field or parameter.
• Making an optional field required.
• Narrowing allowed values, for example removing an enum value.

Additive changes such as a new optional field are usually fine, but a client with strict parsing can still fail.

Step 1: diff the contract at base and head#

Compare the OpenAPI document on the pull request's base commit with the head commit. Open-source tools such as oasdiff list breaking-change rules and run in CI. This tells you what changed.

Step 2: find who is affected#

A diff does not say which services call the changed field. List the consumer repositories, search for client calls to that path, and trace how the response is used. Doing this by hand across many repositories is slow, so teams often skip it.

Step 3: record what you could not verify#

Dynamic URLs, generated clients, and services outside your repositories hide callers. Write the gaps into the pull request instead of reading silence as proof.

Where Impact Gate fits#

Impact Gate compares supported OpenAPI 3 contracts on a pull request, inspects the consumer repositories you selected, and posts an advisory report with source references and coverage notes. It recognizes supported HTTP client patterns in JavaScript, TypeScript, and Java. It does not block merges, and it reports when it cannot reach a conclusion.