Detect API Breaking Changes in CI/CD

Your CI/CD pipeline runs linting, unit tests, integration tests, and maybe even security scans. But does it catch API breaking changes? If you're consuming third-party APIs — and every modern application does — a silent schema drift can take down production with no warning.

This guide shows you how to add API schema validation to your pipeline, which tools to use, and why pipeline validation alone isn't enough.

What Counts as a Breaking Change?

Not all API changes are breaking. Understanding the distinction is the first step to building effective validation:

Breaking changes (require consumer code updates):

Removing an endpoint
Removing a response field
Changing a field's data type
Making an optional request parameter required
Changing authentication requirements
Modifying error response structure

Non-breaking changes (safe to deploy):

Adding a new endpoint
Adding an optional field to a response
Adding an optional query parameter
Adding a new enum value (if your code handles unknowns)

Adding Schema Validation to Your Pipeline

Step 1: Store the Baseline Schema

Commit the OpenAPI/Swagger spec of every third-party API you depend on into your repository. Yes, even if it's not your API. This is your contract baseline.

# Directory structure
specs/
  stripe-v2024-01-15.json
  sendgrid-v3.json
  twilio-2010-04-01.json

Step 2: Fetch the Current Schema

In your CI pipeline, fetch the current schema from the API provider (if they publish it) and compare it against your stored baseline.

# Example: fetching Stripe's OpenAPI spec
curl -s https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json \
  -o specs/stripe-current.json

Step 3: Run a Diff Tool

Several tools can diff OpenAPI specs and identify breaking changes:

openapi-diff

# Install
npm install -g openapi-diff

# Compare
openapi-diff specs/stripe-baseline.json specs/stripe-current.json \
  --fail-on-breaking

Returns exit code 1 if breaking changes are found — perfect for CI gates.

oasdiff

# Install
go install github.com/tufin/oasdiff@latest

# Compare
oasdiff breaking specs/stripe-baseline.json specs/stripe-current.json

Outputs a detailed list of breaking changes with severity levels.

Spectral (linting only)

# Install
npm install -g @stoplight/spectral-cli

# Lint a spec for style violations
spectral lint specs/my-api.yaml --ruleset .spectral.yaml

Spectral validates your own API spec for style and consistency. It doesn't diff against external specs, but it's excellent for enforcing your own API design guidelines.

Step 4: Gate the Build

Add the diff step to your CI config. Here's a GitHub Actions example:

name: API Schema Check
on: [pull_request, schedule]
jobs:
  check-schemas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Fetch current schemas
        run: ./scripts/fetch-schemas.sh
      - name: Check for breaking changes
        run: |
          for spec in specs/*-baseline.json; do
            name=$(basename "$spec" -baseline.json)
            openapi-diff "$spec" "specs/${name}-current.json" \
              --fail-on-breaking || \
              echo "::error::Breaking change detected in $name"
          done

Run this on every PR and on a daily schedule. Daily runs catch upstream changes even when you're not actively developing.

Tools Comparison

Tool	Language	Diff	Lint	CI Integration	Best For
openapi-diff	Node.js	Yes	No	Exit codes	Simple breaking change detection
oasdiff	Go	Yes	Yes	Exit codes, CI action	Detailed breaking change reports
Spectral	Node.js	No	Yes	Exit codes, rulesets	API design linting
swagger-diff	Java	Yes	No	Maven/Gradle	Java/Spring projects
openapi-generator	Multi	No	No	Build step	Type-safe client generation

The Limits of CI-Based Validation

CI-based schema validation is necessary but not sufficient. Here's why:

You Can Only Diff What You Store

If a dependency adds a new endpoint that deprecates the one you use, your stored spec won't show a breaking change. The old endpoint still works — until it doesn't.

Scheduled Runs Have Gaps

Daily schema checks mean up to 24 hours of blind spot. If a critical API pushes a breaking change at 9 AM and you deploy at 10 AM, your pipeline won't catch it until the next scheduled run.

Not All Providers Publish Specs

Many APIs don't publish machine-readable OpenAPI specs. You're left monitoring changelogs manually or reverse-engineering specs from documentation.

Real-World Drift

APIs sometimes change behavior without changing their schema. A field that always returned a string might start returning null. An endpoint that accepted 100 items might now reject batches over 50. Schema validation catches structural changes, not behavioral ones.

Complementary: External Schema Monitoring

This is where external monitoring fills the gap. A tool like SchemaWatch continuously monitors third-party APIs outside your pipeline:

Real-time detection — Changes are caught within hours, not days
No stored specs required — The tool tracks specs on its own
Behavioral monitoring — Some tools test actual API responses, not just schema structure
Centralized alerts — One dashboard for all your dependencies, not scattered CI logs

The ideal setup combines both approaches:

CI validation gates your PRs with spec diffs for APIs you've explicitly stored
External monitoring watches all your dependencies continuously and alerts your team via Slack/email/webhook

Getting Started Checklist

Inventory all third-party APIs your application uses
For each, find and store the current OpenAPI/Swagger spec
Add openapi-diff or oasdiff to your CI pipeline
Set up a daily scheduled run (not just PR-triggered)
Configure alerting: Slack webhook for CI failures
Sign up for external monitoring for continuous coverage
Review and update stored specs quarterly

Breaking changes are inevitable. The question isn't whether they'll happen — it's whether you'll catch them in your pipeline or in your production logs.

Detect API Breaking Changes in CI/CD: A Complete Pipeline Setup