API Sentinel

Automated breaking change detection for APIs.

API Sentinel monitors OpenAPI schemas over time and alerts you when breaking changes are detected. Run it in CI/CD to catch API regressions before they hit production.

Why This Matters

APIs evolve, and breaking changes slip through more often than anyone admits. A renamed field, a removed endpoint, a type change—these can cascade into production incidents when downstream consumers aren't prepared.

API Sentinel gives you:

• Daily schema snapshots so you have a record of what changed and when
• Smart diff detection that understands OpenAPI semantics, not just JSON structure
• Breaking change classification based on real compatibility rules
• Slack alerts so your team knows immediately when something breaks

Installation

pip install api-sentinel

Or install from source:

git clone https://github.com/yourusername/api-sentinel.git
cd api-sentinel
pip install -e .

Quick Start

1. Initialize configuration:

api-sentinel init

2. Edit config.yaml to add your APIs:

apis:
  - name: my-api
    schema_url: https://api.example.com/openapi.json
    check_interval: daily

3. Run a check:

api-sentinel check

Usage

Commands

# Initialize a new config file
api-sentinel init

# Check all configured APIs
api-sentinel check

# Check a specific API
api-sentinel check --api stripe

# Dry run (don't save snapshots or send alerts)
api-sentinel check --dry-run

# View available reports
api-sentinel report

# Show the latest report for an API
api-sentinel report --api my-api --latest

# List configured APIs
api-sentinel list-apis

Configuration

API Sentinel uses a YAML config file. Here's a full example:

apis:
  # Public API (no auth needed)
  - name: petstore
    schema_url: https://petstore3.swagger.io/api/v3/openapi.json
    check_interval: daily

  # API with bearer token auth
  - name: stripe
    schema_url: https://api.stripe.com/openapi/spec3.json
    auth:
      type: bearer
      token_env: STRIPE_API_KEY
    check_interval: daily

  # Local schema file
  - name: internal
    schema_path: ./schemas/internal-api.json

settings:
  snapshots_dir: snapshots
  reports_dir: reports
  keep_snapshots: 30

notifications:
  console: true
  slack_webhook_env: SLACK_WEBHOOK_URL

Authentication

API Sentinel supports several auth methods. Credentials are always read from environment variables for security.

Bearer Token:

auth:
  type: bearer
  token_env: MY_API_TOKEN

API Key:

auth:
  type: api_key
  key_env: MY_API_KEY
  header: X-API-Key  # optional, defaults to X-API-Key

Basic Auth:

auth:
  type: basic
  user_env: API_USER
  pass_env: API_PASSWORD

Breaking Change Rules

API Sentinel classifies changes based on whether they would break existing API consumers:

Breaking:

• Endpoint removed
• HTTP method removed
• Required field added to request
• Field removed from response
• Type changed
• Enum value removed

Non-breaking:

• New endpoint added
• Optional field added
• New enum value added
• Description changed

CI/CD Integration

GitHub Actions

Add this workflow to check schemas daily:

name: API Schema Check

on:
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - run: pip install api-sentinel

      - name: Restore snapshots
        uses: actions/cache@v4
        with:
          path: snapshots
          key: snapshots-${{ github.ref_name }}

      - name: Check schemas
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: api-sentinel check

      - name: Save snapshots
        uses: actions/cache/save@v4
        if: always()
        with:
          path: snapshots
          key: snapshots-${{ github.ref_name }}-${{ github.run_id }}

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=api_sentinel

# Type checking
mypy src/api_sentinel

# Linting
ruff check src/

Project Structure

api-sentinel/
├── src/api_sentinel/
│   ├── fetcher/       # Schema fetching and normalization
│   ├── store/         # Snapshot storage
│   ├── diff/          # Schema comparison engine
│   ├── classifier/    # Breaking change rules
│   ├── notifier/      # Slack and console notifications
│   ├── reporter/      # Markdown and HTML reports
│   ├── cli.py         # Command-line interface
│   ├── config.py      # Configuration handling
│   └── core.py        # Main orchestration
├── tests/
├── examples/
└── .github/workflows/

Roadmap

• GraphQL schema support
• AsyncAPI support for event-driven APIs
• Web dashboard for viewing change history
• Custom rule definitions
• API stability scoring

License

MIT