Catch breaking API changes before they merge
Nobody decides to break an API. It happens in a pull request that looks harmless: a field is renamed for consistency, an optional parameter becomes required because the new code needs it, an endpoint that "nobody uses" is removed. The tests pass, because the tests were changed in the same pull request. The clients find out in production.
If the API is described in an OpenAPI file in Git, this is a problem a machine can catch. Both versions of the contract are in the history, and comparing them takes one command. This post shows the command, what it reports, what it does not, and how to make it a check on every pull request.
One command, two versions
The apigit command line compares two versions of an OpenAPI document. It needs no account and works offline:
npm install -g @apigit/cli
apigit diff v1.yaml v2.yaml
Here is what it prints for a small Orders API where a pull request removed the cancel operation, added a required currency to the order request, dropped note from the response, and added a filter and a timestamp:
5 change(s), 3 breaking.
Breaking
DELETE /orders/{orderId}: operation removed
schema NewOrder: schema field "currency" added (required)
schema Order: schema field "note" removed
Not breaking
GET /orders: parameter query customerId added
schema Order: schema field "createdAt" added
The breaking changes come first, and each line says where and what. apigit breaking prints only the first group and exits with 1 when it is not empty:
$ apigit breaking v1.yaml v2.yaml
3 change(s), 3 breaking.
Breaking
DELETE /orders/{orderId}: operation removed
schema NewOrder: schema field "currency" added (required)
schema Order: schema field "note" removed
error: 3 breaking change(s) from v1.yaml to v2.yaml
The two arguments can be files, as above, or Git refs. In a repository you compare branches, tags or commits and name the file:
apigit breaking origin/main HEAD openapi/orders.yaml
apigit diff v1.2.0 v1.3.0 openapi/orders.yaml
Both versions are bundled before they are compared, so a change in a file that the document refers to is found as well.
What counts as breaking
The rule behind the list is simple: a change is breaking when a client written against the old contract can fail against the new one.
| Change | Breaking? |
|---|---|
| Operation removed | Yes |
| Operation added or deprecated | No |
| Parameter's type changed | Yes |
| Parameter removed | Only a path parameter: a query or header parameter the server no longer reads is reported as not breaking |
| Parameter added | Only when it is required |
| Parameter or request field became required | Yes |
| Request body added | Only when it is required |
| Response status removed | Yes |
| Response status added | No |
| Field removed from a response | Yes |
| Field removed from a request | Only when it was required |
| Field added to a response | No |
| Required field added to a request | Yes |
| Type of a field changed | Yes |
| Schema removed | Yes |
Requests and responses are judged in opposite directions, which is the part people get wrong by hand. Adding a field to a response is safe, because a client ignores what it does not know. Adding a required field to a request is not, because the old client does not send it.
What it does not catch
The comparison reads structure: operations, parameters, fields, types and what is required. It does not weigh every constraint. In the same example the pull request also lowered the maximum of limit from 100 to 50 and added the value refunded to the status enum of the response. Both can break a client, and neither is in the report.
Three kinds of change stay with the reviewer:
- Tightened limits and changed enums: a smaller maximum, a new pattern, a value added to a response enum that a client's
switchdoes not handle. - Behaviour behind an unchanged contract: the same field with a different meaning, a different default, a different order of results.
- Everything the document does not describe: an undocumented header that clients came to rely on.
A green check means the structural contract is intact. It is the floor of a review, not all of it.
Make it a pull request check
In GitHub Actions:
name: API contract
on: pull_request
jobs:
contract:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the base branch is needed for the comparison
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npx @apigit/cli lint openapi/orders.yaml --format github-actions
- run: npx @apigit/cli breaking origin/${{ github.base_ref }} HEAD openapi/orders.yaml
The first step lints the document with the same rule sets as the APIGit editor and annotates the findings on the pull request. The second fails the job when the pull request breaks the contract. On any other CI system the same two commands run with npx.
If the repository is hosted on APIGit, one more command posts the lint result as a commit status that branch protection can require before a merge, with your organization's rule sets applied:
apigit lint --org acme --report-status
When the break is intended
Sometimes the change is right and the contract must break. The check has still done its job: the break is now a decision, visible in the pull request, and not an accident. What teams usually do then:
- Publish it as a new version. On APIGit a published document version is a name pointing at a commit, so
v1keeps serving the old contract to its readers whilev2describes the new one. See Pin or follow a branch. - Deprecate before removing. Mark the operation
deprecated: truein one release, which the comparison reports as not breaking, and remove it in a later one. - Put the report in the changelog.
apigit diff v1.2.0 v1.3.0 openapi/orders.yamlbetween two tags is most of a changelog entry. - Merge deliberately. Let a maintainer override the failed check for that pull request, with the reason in the description.
Ask an agent the same question
The same comparison is available to AI agents. With the APIGit MCP server connected, Claude, Cursor or VS Code can answer "what changed in the orders API between v1.2.0 and main, and does it break anyone?" from your repository, using the same rules as the command line. See APIGit for AI agents.
The commands are documented in the CLI reference.