Metadata-Version: 2.4
Name: api-sentinel-cli
Version: 0.1.2
Summary: Automated breaking change detection for APIs
Author-email: Jeryn Vicari <jeryn@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/jerynv/api-sentinel
Project-URL: Repository, https://github.com/jerynv/api-sentinel
Project-URL: Issues, https://github.com/jerynv/api-sentinel/issues
Keywords: api,openapi,schema,breaking-changes,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0.0
Requires-Dist: jsonref>=1.0.0
Requires-Dist: deepdiff>=6.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: responses>=0.22.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install api-sentinel-cli
```

Or install from source:

```bash
git clone https://github.com/jerynv/api-sentinel.git
cd api-sentinel
pip install -e .
```

## Quick Start

1. Initialize configuration:

```bash
api-sentinel init
```

2. Edit `config.yaml` to add your APIs:

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

3. Run a check:

```bash
api-sentinel check
```

## Usage

### Commands

```bash
# 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:

```yaml
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:**
```yaml
auth:
  type: bearer
  token_env: MY_API_TOKEN
```

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

**Basic Auth:**
```yaml
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:

```yaml
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

```bash
# 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
