Monitor a third-party API for breaking changes

When you integrate an API you don't control (a marketplace, a payment provider, a partner platform), a breaking change on their side breaks your integration whether or not you ship anything. If the provider publishes an OpenAPI spec, oasdiff tells you exactly what changed between two snapshots, so a removed field or a tightened type surfaces before it reaches production.

The idea

Keep a baseline copy of the provider's spec, then periodically compare the live spec against it. oasdiff reports what changed and, with breaking, exits non-zero when a change would break existing clients, so you can wire it into a schedule or an alert.

A one-off check

# Save a baseline snapshot of the provider's spec
curl -sSL https://api.example.com/openapi.yaml -o baseline.yaml

# Later, see exactly what changed since the baseline
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml

Want only the changes that would break your integration, with a non-zero exit code for automation?

# Just the breaking changes, with a non-zero exit code you can act on
oasdiff breaking baseline.yaml https://api.example.com/openapi.yaml --fail-on ERR

The changelog prints readable text by default. Pass -f markdown or -f html to produce a document you can publish, attach to a ticket, or commit to a repo (and -f json / -f yaml if you want to process it).

# A changelog you can publish or attach: Markdown or HTML
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml -f markdown > changelog.md
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml -f html > changelog.html

Keep a tracked changelog in a repo

Run the check on a schedule and commit the result, so the repo becomes a version-controlled history of how the API you depend on has changed over time. This GitHub Actions workflow fetches the provider's spec daily and, whenever it changed, commits a dated Markdown changelog and advances the baseline:

name: provider-api-changelog
on:
  schedule:
    - cron: "0 8 * * *"      # daily at 08:00 UTC
  workflow_dispatch:
permissions:
  contents: write            # commit the changelog back to the repo
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Fetch the provider's current spec
        run: curl -sSL https://api.example.com/openapi.yaml -o latest.yaml
      - name: On a change, write a dated Markdown changelog and commit it
        run: |
          if cmp -s baseline.yaml latest.yaml; then echo "No change."; exit 0; fi
          mkdir -p changelog
          docker run --rm -v "$PWD:/w" -w /w tufin/oasdiff changelog baseline.yaml latest.yaml -f markdown > "changelog/$(date +%F).md"
          cp latest.yaml baseline.yaml
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add baseline.yaml changelog/
          git commit -m "Provider API change $(date +%F)"
          git push

Each commit is a snapshot plus the diff that produced it, so the changelog/ folder reads as a running digest, and anyone watching the repo gets notified on every change. Not on GitHub? The same two steps (fetch, then oasdiff breaking ... --fail-on ERR) run from a plain cron job that emails you when a breaking change appears.

Good to know

• This needs the provider to publish a machine-readable spec that they keep current. Many publish a Postman collection too; if that's all they offer, export it to OpenAPI (Postman does this) and diff successive exports. If a provider publishes nothing machine-readable, spec diffing can't catch their changes on its own (a spec you hand-maintain only changes when you already noticed something), so that case needs live response monitoring, a different kind of tool.
• External $ref URLs in the spec are not resolved by default (a safety default). Pass --allow-external-refs only for specs you trust.
• oasdiff detects every way a change can affect an existing client, across the whole spec. The breaking change rules list what it checks.

Prefer the browser, or want to try it on two specs first? The diff tool runs the same checks with no install. If you publish APIs of your own, those same checks run on your pull requests with the GitHub Action.