APIGit
Native Git RepositoryVersioned, Git-native API repositoryAPI DesignOpenAPI, AsyncAPI and GraphQL editingAPI DocumentationPublish versioned docs from GitAPI GovernanceCheck OpenAPI and AsyncAPI standardsMock ServerFrom OpenAPI, GraphQL or Express.js codeTeam CollaborationOrganizations, teams, permissions and reviewsAI AgentsMCP server, llms.txt and Copy page for agentsCLILocal-first: lint, mock and publish from a terminal

Your API and docs are a Git repository

Specs and Markdown guides in one repository, reviewed like code and published as a docs site, mocks and agent-ready endpoints from any commit.

Start for freeView pricing

Learning

DocumentationGetting StartedVideo TutorialsBlog

Support

Contact UsRequest a DemoReport an Issue
DocsPricingAbout
Sign inStart for free
APIGit

The Git-native, local-first API platform, ready for AI agents.

Product

  • Git repository
  • API design
  • API documentation
  • API governance
  • Mock server
  • Team collaboration
  • AI agents
  • CLI

Resources

  • Documentation
  • Get started
  • CLI reference
  • MCP server
  • Blog
  • Video tutorials
  • Pricing

Company

  • About
  • Careers
  • Contact
  • Privacy policy
  • Terms of service
  • Service level agreement
  • Cookie policy

© 2026 APIGit. All rights reserved.

Blog/API Design

Catch breaking API changes before they merge

Nov 18, 20266 min readAPIGit Team

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.

ChangeBreaking?
Operation removedYes
Operation added or deprecatedNo
Parameter's type changedYes
Parameter removedOnly a path parameter: a query or header parameter the server no longer reads is reported as not breaking
Parameter addedOnly when it is required
Parameter or request field became requiredYes
Request body addedOnly when it is required
Response status removedYes
Response status addedNo
Field removed from a responseYes
Field removed from a requestOnly when it was required
Field added to a responseNo
Required field added to a requestYes
Type of a field changedYes
Schema removedYes

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 switch does 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 v1 keeps serving the old contract to its readers while v2 describes the new one. See Pin or follow a branch.
  • Deprecate before removing. Mark the operation deprecated: true in 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.yaml between 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.

More posts

  • Nov 13, 2026AsyncAPI governance, GraphQL mocks and agent pages are liveAPI Design
  • Nov 13, 2026AsyncAPI and GraphQL join OpenAPI in APIGitAPI Design
  • Mar 15, 2024oneOf, allOf and anyOf in OpenAPI, and the mistakes that reach productionAPI Design
All posts

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Start for free Book a demo

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish