api-sentinel-cli 0.1.2

Automated breaking change detection for APIs

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-cli

Or install from source:

git clone https://github.com/jerynv/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-cli

      - 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