Detect breaking API changes in CI with API Contract Guardian

Product: API Contract Guardian · Category: API Governance · Tags: OpenAPIbreaking changesCI/CDcontract testingAPI governance

Your API contract changed on a feature branch. Did anyone notice before merge? API Contract Guardian compares OpenAPI specs between branches, detects every category of breaking change, generates a migration guide — and exits non-zero so your CI pipeline blocks the PR.

Breaking API changes are the single most expensive bug you can ship: every consumer that depends on the old contract breaks simultaneously. Manual code review catches some of them, but the subtle ones — a required property added here, a response type changed there — slip through. API Contract Guardian gives you a deterministic, automated check that runs in every CI pipeline.

Why breaking API changes are hard to catch

In a REST API defined by an OpenAPI 3.x spec, there is no compile-time check that v2 of your schema is backward-compatible with v1. A PR that removes an endpoint, changes a field type, or adds a required property looks fine in isolation — the tests pass, the code builds. But the moment you deploy, every client that expected the old contract starts failing.

Existing approaches fall short:

Manual review: reviewers must diff two spec files side-by-side and know every backward-compatibility rule for OpenAPI — easy to miss a renamed field or a removed property buried in a $ref chain.
Integration tests: they catch runtime breakage but only after deploy. By then the damage is done.
SDK regeneration: regenerating clients after the fact is reactive, not preventive.

What you need is a pre-merge gate that runs during CI, compares the PR's spec against the base branch, and fails the build if any breaking change exists — with a clear report of exactly what changed and how to migrate.

Install API Contract Guardian

Python 3.10+ required. API Contract Guardian is not on public PyPI — install via git, Homebrew, or Scoop.

pip install git+https://github.com/Coding-Dev-Tools/api-contract-guardian.git

Or via Homebrew (macOS/Linux): brew tap Coding-Dev-Tools/tap && brew install api-contract-guardian — or Scoop (Windows): scoop bucket add Coding-Dev-Tools https://github.com/Coding-Dev-Tools/scoop-bucket && scoop install api-contract-guardian. See the repo for details.

Quick start

Compare two OpenAPI spec files and see the breaking changes:

api-contract-guardian check spec-v1.yaml spec-v2.yaml

The check command compares every path, operation, parameter, schema, and property. It exits non-zero if any breaking change is detected — perfect for CI gating. Use --format json or --format yaml for machine-readable output, or pipe the diff into your existing PR comment workflow.

Generate a human-readable migration guide for API consumers:

api-contract-guardian migrate spec-v1.yaml spec-v2.yaml --output MIGRATION.md

Use cases

CI/CD gating: Block PRs that introduce breaking API changes — fail the build before merge with a clear diff report.
API version upgrades: When bumping v1 → v2, auto-generate a migration guide for consumers so they know exactly what changed.
Microservice contract enforcement: Ensure every service's OpenAPI contract stays backward-compatible across deploys in a multi-repo architecture.
Client SDK regeneration: Know the exact change set so SDK clients can be regenerated with confidence — no guesswork.
Pre-release audit: Run check on every release candidate spec to certify no accidental breakage shipped.

Features

Feature	Detail
Breaking change detection	Removed endpoints, changed types, renamed fields, removed properties, required properties added, response format changes, endpoint auth changes — 7 categories covered
Migration guide generation	Produces human-readable markdown migration docs from a diff, ready to publish alongside a changelog
Multiple output formats	Rich (terminal), JSON, YAML, or Markdown — pipe into PR comments, dashboards, or CI logs
CI gating	Exits non-zero on breaking changes — native GitHub Actions, GitLab CI, Jenkins, and any pipeline that checks exit codes
OpenAPI 3.x support	Full support for OpenAPI 3.0.x and 3.1.x specs, including $ref resolution and inline schemas
Git branch diffing	Compare specs between branches, tags, or commits — not just local files

Comparison: API Contract Guardian vs alternatives

Capability	DIY diff script	API Contract Guardian
Structured OpenAPI diff engine	❌ (raw yaml/python dict diff)	✅ (schema-aware, understands $ref, type changes, required semantics)
7 breaking-change categories	❌	✅ removed endpoint, changed type, renamed field, removed property, required added, response changed, auth changed
Migration guide generation	❌	✅ auto-generates markdown migration docs
CI gating (non-zero exit)	✅ (with scripting)	✅ native exit codes + format flags for PR comments
Git branch diffing	❌ (would need git plumbing)	✅ compare via branches, tags, or commits
Multiple output formats	⚠️ single format	✅ Rich / JSON / YAML / Markdown
OpenAPI 3.0 + 3.1 support	⚠️ (must handle yourself)	✅ native, including $ref chains
Zero-config install	N/A	✅ one pip/git command, no external services
MIT license	N/A	✅ fully open source

A DIY diff script might catch basic key-level changes, but it won't understand OpenAPI semantics — a renamed field from name to fullName looks like deletion + addition to a plain yaml diff, not like a rename. API Contract Guardian is schema-aware down to the property level and handles $ref resolution, type coercion, and required-semantics correctly.

Pricing

Free tier covers 1 spec comparison — enough to try it in a single PR. Unlock unlimited specs, CI/CD gating, and migration guide generation with the ACG Individual plan or bundle all 11 tools via the Suite plan.

Plan	Price	Best For
Free	$0	Individual devs, OSS — CLI only, 1 spec comparison
ACG Individual	$19/mo ($15/mo annual)	Professional devs — unlimited specs, CI/CD gating, migration guides
Suite (all 11 tools)	$49/mo ($39/mo annual)	Full Coding Dev Tools toolkit — 40% savings vs buying individually
Team	$79/mo ($63/mo annual)	Up to 5 devs — shared dashboards, alerts, run history

No lock-in: CLI works fully offline on the free tier — no telemetry, no phone-home.

Key takeaways

API Contract Guardian compares OpenAPI 3.x specs and detects 7 categories of breaking changes — removed endpoints, changed types, renamed fields, removed properties, required additions, response changes, and auth changes.
It exits non-zero on breaking changes, making it a drop-in CI gate for any pipeline that checks exit codes — GitHub Actions, GitLab CI, Jenkins, or CircleCI.
A migrate command generates human-readable migration guides from the diff, so consumers know exactly what changed and how to adapt.
Git branch diffing lets you compare specs between branches, tags, or commits — not just local files, so it works naturally in CI against the base branch spec.
Free tier is genuinely useful (1 spec comparison, fully offline). Paid tiers unlock unlimited usage and CI/CD gating at $19/mo.

Next steps

Star API Contract Guardian on GitHub — ⭐ helps other devs find it
DevForge pricing →

Verification notes

All claims verified against api-contract-guardian/README.md (2026-07-15). Install: pip install git+https://github.com/Coding-Dev-Tools/api-contract-guardian.git (not on public PyPI — live JSON API probe returned 404). CLI entry point: api-contract-guardian. Pricing: Free $0, ACG Individual $19/mo, Suite $49/mo (all 11 tools), Team $79/mo. Supported: OpenAPI 3.0.x + 3.1.x; output formats Rich/JSON/YAML/Markdown; breaking change categories per feature table. MIT license. Homebrew/Scoop available per README.