diffapi

Detect API response schema drift before it breaks your app.

diffapi is a lightweight CLI tool that monitors API endpoints for schema changes. It records response schemas, compares them over time, and alerts you to breaking changes like removed fields, type changes, or new required fields.

Perfect for:

• CI/CD pipelines testing third-party APIs
• Monitoring APIs you depend on but don't control
• Catching undocumented API changes early
• Tracking API evolution over time

Zero dependencies. Pure Python stdlib only.

Installation

pip install diffapi

Or run directly:

curl -O https://raw.githubusercontent.com/kriskimmerle/diffapi/main/diffapi.py
chmod +x diffapi.py
./diffapi.py --help

Quick Start

# Record a baseline schema
diffapi record https://api.example.com/users

# Later, check for changes
diffapi diff https://api.example.com/users

Usage

Record a Schema Snapshot

diffapi record https://api.example.com/users

This fetches the API response and stores the schema in .diffapi/schemas/.

Compare Against Latest Snapshot

diffapi diff https://api.example.com/users

Output:

✅ Response received (HTTP 200)

📊 Comparing against snapshot from 2025-02-01T10:30:00

🚨 BREAKING CHANGES (2):
  - Field removed: $.user.email
  ~ Type changed at $.user.age: string → integer

⚠️  WARNINGS (1):
  ~ Nullable changed at $.user.phone: False → True

ℹ️  INFO (1):
  + Field added: $.user.avatar_url

Authentication

diffapi record -H "Authorization: Bearer your-token" https://api.example.com/users
diffapi diff -H "Authorization: Bearer your-token" https://api.example.com/users

CI Mode

Exit with code 1 if breaking changes are detected:

diffapi diff --check https://api.example.com/users

Perfect for CI pipelines:

# .github/workflows/api-check.yml
name: API Schema Check
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check API schema
        run: |
          pip install diffapi
          diffapi diff --check https://api.partner.com/v1/data

Watch Multiple Endpoints

Create a config file:

{
  "endpoints": [
    {
      "url": "https://api.example.com/users",
      "headers": {
        "Authorization": "Bearer token123"
      }
    },
    {
      "url": "https://api.example.com/posts"
    }
  ]
}

Run:

diffapi watch config.json

View History

diffapi history https://api.example.com/users

Output:

📚 Snapshot history for https://api.example.com/users:

  2025-02-01T14-30-00.123456
  2025-02-01T10-15-00.123456
  2025-01-31T22-00-00.123456

Total: 3 snapshots

Change Detection

Change Type	Severity	Description
Field removed	🚨 BREAKING	A field that existed before is now missing
Type changed	🚨 BREAKING	Field type changed (e.g., string → number)
Nullable changed (now required)	🚨 BREAKING	Field that was nullable is now required
Nullable changed (now optional)	⚠️ WARNING	Field that was required is now nullable
Field added	ℹ️ INFO	A new field appeared in the response

How It Works

1. Schema Extraction: Recursively walks JSON responses and extracts:

   • Field names and paths
   • Data types (string, number, boolean, array, object, null)
   • Nullability
   • Array item types
   • Nested object structures

2. Storage: Schemas are stored as JSON in .diffapi/schemas/ with timestamps. By default, keeps the 10 most recent snapshots per endpoint.

3. Diffing: Compares new schemas against the latest snapshot, detecting:

   • Missing fields
   • New fields
   • Type mismatches
   • Nullability changes

4. Reporting: Color-coded output with severity levels (BREAKING, WARNING, INFO)

Advanced Options

Save New Snapshot After Comparison

diffapi diff --save https://api.example.com/users

JSON Output

diffapi diff --format json https://api.example.com/users

Custom Snapshot Directory

diffapi --base-dir ./api-snapshots record https://api.example.com/users

Limit Snapshot History

diffapi record --max-snapshots 5 https://api.example.com/users

Use Cases

Monitor Third-Party APIs

# Daily cron job
0 9 * * * cd /your/project && diffapi diff --check https://api.partner.com/data

Pre-Deployment Checks

# In your CI pipeline
diffapi diff --check https://staging-api.yourapp.com/endpoint || exit 1

API Version Comparison

diffapi record https://api.example.com/v1/users
diffapi record https://api.example.com/v2/users
# Compare the snapshots to see what changed between versions

Examples

See the examples/ directory for:

• CI/CD integration examples
• GitHub Actions workflows
• Docker usage
• Config file templates

Why diffapi?

• Zero dependencies: Uses only Python stdlib (urllib, json, pathlib)
• Simple: One command to record, one to compare
• CI-friendly: Exit codes and JSON output for automation
• Lightweight: Single Python file, ~500 lines
• Fast: Snapshots are local, no external services required

Limitations

• Only supports JSON responses (not XML, HTML, etc.)
• Assumes GET requests (POST/PUT support coming soon)
• Schema inference is based on first array element
• No support for OAuth flows (use headers for Bearer tokens)

Contributing

Issues and PRs welcome at https://github.com/kriskimmerle/diffapi

License

MIT License - see LICENSE

Author

Created by Kris Kimmerle (@kriskimmerle)

---

Built with ❤️ for developers who hate API surprises.