PactWatch

Your microservices have a contract. PactWatch enforces it before merge.

An OpenAPI breaking-change detector that knows which downstream consumers will actually break. Most API diff tools tell you what changed. PactWatch tells you who cares.

The Problem

Team A changes their API. Team B's mobile app breaks in production. The spec diff showed "field removed" — but nobody connected it to Team B.

PactWatch maintains a service-to-consumer graph (pactwatch.yaml). When a producer's spec changes, it classifies each change as BREAKING, RISKY, or SAFE, then filters the results per consumer. Same spec change, different verdict per team.

How It Works

1. Diff    — structurally compare two OpenAPI 3.x specs
2. Classify — label each change: BREAKING / RISKY / SAFE
3. Filter  — check the consumer graph: who uses the affected endpoints?

Installation

pip install pactwatch

Quick Start

Raw diff (Phase 1)

Compare two specs and get classified changes:

# Rich terminal output
pactwatch diff old-spec.yaml new-spec.yaml

# JSON for CI
pactwatch diff old-spec.yaml new-spec.yaml --format json

Per-consumer impact (Phase 2)

Define your service topology in pactwatch.yaml:

version: 1
producers:
  api:
    spec: ./services/api/openapi.yaml

consumers:
  mobile-app:
    consumes:
      - producer: api
        endpoints:
          - GET /users/{id}
          - POST /orders
  web-dashboard:
    consumes:
      - producer: api
        endpoints:
          - GET /users/{id}
          - GET /admin/*

Then check per-consumer impact:

# Check all consumers
pactwatch check -c pactwatch.yaml -p api --old old.yaml --new new.yaml

# Check a single consumer
pactwatch check -c pactwatch.yaml -p api --old old.yaml --new new.yaml --consumer mobile-app

# JSON for CI
pactwatch check -c pactwatch.yaml -p api --old old.yaml --new new.yaml -f json

GitHub Action (Phase 3)

Add to your workflow:

name: API Contract Check
on: pull_request

jobs:
  pactwatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pyjeebz/pactwatch@v1
        with:
          config: pactwatch.yaml
          producer: api
          old-spec: services/api/openapi.yaml  # from base branch
          new-spec: services/api/openapi.yaml  # from PR branch
          github-token: ${{ secrets.GITHUB_TOKEN }}

PactWatch will:

• Post a PR comment showing per-consumer impact
• Set a commit status check (pass/fail)
• Exit with code 1 if breaking changes affect any consumer

Classification Rules

Breaking

Risky

Safe

CLI Reference

pactwatch diff

pactwatch diff OLD NEW [--format text|json]

Compare two OpenAPI specs. Exits with code 1 if BREAKING changes found.

pactwatch check

pactwatch check --config PATH --producer NAME --old PATH --new PATH
                [--consumer NAME] [--format text|json]

Check per-consumer impact using the consumer graph. Exits with code 1 if any consumer has BREAKING changes.

Exit Codes

Demo

See the demo monorepo for a working example with 3 services.

# Run the demo
pactwatch check \
  -c examples/demo-monorepo/pactwatch.yaml \
  -p user-api \
  --old examples/demo-monorepo/services/producer-api/openapi.yaml \
  --new examples/demo-monorepo/services/producer-api/openapi-breaking.yaml

License

Apache 2.0