GitHub - aj9704845-code/api-impact-tracker: Know exactly which API clients you'll break before you deploy

🔍 API Impact Tracker

Know exactly which clients you'll break before you deploy.

The Problem

You're about to remove an endpoint from your API. Do you know which clients will break?

Most teams don't. They:

🔥 Deploy breaking changes blindly
📧 Get angry emails from customers
🚨 Spend hours debugging who's affected
💸 Lose revenue from broken integrations

The Solution

API Impact Tracker automatically tracks which clients use which endpoints, then alerts you before you break production.

$ api-impact diff openapi.yaml

⚠️  BREAKING CHANGES DETECTED!

DELETE /users/{id}
Severity: 🔴 HIGH

Clients affected:
  📱 acme-inc (2h ago)
  📱 foo-app (3 days ago)

⚠️  ACTION REQUIRED: This endpoint is NOT in OpenAPI but clients still use it!

🔍 Detect Breaking Changes Before Deploy

📊 Tracked Endpoints

Features

🎯 Zero Config - Drop-in middleware, works in minutes
🔒 Privacy First - All data stored locally (SQLite)
📊 Smart Detection - Normalizes paths (/users/123 → /users/{id})
⚡ Fast - No performance impact on your API
🚀 CI/CD Ready - GitHub Action included
📈 Export - JSON, Markdown, or GitHub comments

Quick Start

1. Install

npm install api-impact-tracker

2. Add Middleware

import express from 'express';
import { apiImpactMiddleware } from 'api-impact-tracker';

const app = express();

// Add this ONE line
app.use(apiImpactMiddleware({
  clientIdHeader: 'x-api-key' // or 'authorization'
}));

// Your routes...
app.get('/users/:id', (req, res) => { ... });

3. Check Before Deploying

# Compare your OpenAPI spec with real usage
npx api-impact diff openapi.yaml

That's it. You now know exactly who you'll break.

Use Cases

Before Removing an Endpoint

$ api-impact clients DELETE /users/{id}

📱 acme-inc
   └─ 245 calls, last used: 2h ago

📱 foo-app
   └─ 12 calls, last used: 3 days ago

Action: Email these 2 clients before removal.

Find Dead Code

$ api-impact diff openapi.yaml

💀 Unused Endpoints:
  - GET /legacy/stats (declared but NEVER used)
  - PUT /admin/config (declared but NEVER used)

💡 Safe to remove - no clients affected

Action: Clean up 20% of your API surface.

CI/CD Integration

# .github/workflows/api-check.yml
- name: Check API Changes
  run: |
    npx api-impact diff openapi.yaml --ci
    # Fails CI if breaking changes detected

Blocks PRs that would break clients.

CLI Commands

# List all tracked endpoints
api-impact list

# Show which clients use an endpoint
api-impact clients GET /users/{id}

# Compare with OpenAPI spec
api-impact diff openapi.yaml

# Export to JSON
api-impact diff openapi.yaml --format=json --output=report.json

# Export to Markdown
api-impact diff openapi.yaml --format=md --output=REPORT.md

# CI mode (exit 1 if breaking)
api-impact diff openapi.yaml --ci

How It Works

Middleware captures every API request (method, path, client ID)
Normalizer groups similar paths (/users/123 → /users/{id})
Storage saves usage data locally (SQLite, zero overhead)
Diff Engine compares OpenAPI spec vs. real usage
Alerts when you're about to break production

Real-World Impact

Before API Impact Tracker:

Team deploys breaking change
3 enterprise clients break silently
Support tickets flood in
2 days to identify all affected clients
Emergency hotfix + apologies

After API Impact Tracker:

Team runs api-impact diff
Sees 3 clients will break
Emails them 1 week notice
Zero downtime, zero complaints

How Path Normalization Works

Numeric IDs → {id}
UUIDs → {uuid}
Slugs → {slug}

The algorithm is deterministic and documented to avoid false positives.

Configuration

Custom Client Identification

app.use(apiImpactMiddleware({
  clientIdHeader: 'authorization', // Bearer tokens
  // Or extract from JWT:
  extractClientId: (req) => {
    const token = req.headers.authorization;
    return decodeJWT(token).clientId;
  }
}));

Database Location

import { Storage } from 'api-impact-tracker';

const storage = new Storage('./custom/path/usage.db');

GitHub Action

Automatically comment on PRs when OpenAPI changes:

# .github/workflows/api-impact-check.yml
name: API Impact Check

on:
  pull_request:
    paths:
      - 'openapi.yaml'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g api-impact-tracker
      - run: api-impact diff openapi.yaml --format=github

Result: PR gets a comment with full impact analysis.

FAQ

Q: Does this slow down my API?
A: No. Tracking adds <1ms per request. All processing is async.

Q: Where is data stored?
A: Locally in SQLite (./data/usage.db). Never leaves your infrastructure.

Q: What if I don't have an OpenAPI spec?
A: You can still use list and clients commands to see usage data.

Q: Does it work with GraphQL?
A: Not yet, but planned for v2.

Q: Can I self-host everything?
A: Yes! Everything runs locally. No cloud dependencies.

Roadmap

GraphQL support
Automatic client notification emails
Slack/Discord webhooks
Historical trend analysis
Multi-language SDKs (Python, Go, Ruby)

Contributing

PRs welcome! See CONTRIBUTING.md