APIDiff

Real-time API contract drift detector & lightweight sniffing proxy. Protect your frontend from silent backend database type changes, breaking schema shifts, and field removals the millisecond they happen.

---

The Pain

The backend team changes a database column type or schema payload without notifying anyone. Your frontend state management or UI components silently break, and you waste hours debugging local state before realizing the raw network payload structure mutated.

The Solution

APIDiff is a lightweight reverse proxy and local dashboard that sniffs local network traffic, infers JSON schema structures, locks baseline data contracts, and alerts you with visual structural diffs the instant an API contract breaks.

---

Features

• Real-Time Traffic Sniffer: Intercepts HTTP/JSON requests and responses without modifying payload data.
• Automatic Schema Extraction: Infers full JSON schemas (primitives, nested objects, array element types, required keys).
• Millisecond Breaking Change Alerts:
  • Type Mutations: Detects integer ➔ string (99812 ➔ "99812").
  • Field Removals: Flags missing required keys in response bodies.
  • Nullability Violations: Detects when non-null properties suddenly return null.
  • Additive Changes: Tracks newly introduced non-breaking properties.
• TypeScript Type Exporter: Generates .d.ts interface definitions directly from locked baseline schemas.
• JavaScript & Node.js Native Support: Installable via npx / npm and importable into Express/Fastify/Next.js applications.
• Embedded Web Dashboard: Native single-binary web interface accessible at http://localhost:8787 with real-time SSE updates.
• Built-in Contract Simulator: 1-click test triggers (Type Mismatch, Removed Field, Nullability Violation) to test contract alerts instantly.
• Persistent Contract Storage: Saved baseline contracts persist across restarts in ~/.apidiff/baselines.json.

---

Quick Start

1. Go Lang

git clone https://github.com/callmidavid/apidiff.git
cd apidiff
go build -o apidiff cmd/apidiff/main.go
./apidiff --port 8787 --target http://localhost:3000

2. JavaScript & TypeScript

Run directly via npx:

npx apidiff-proxy --port 8787 --target http://localhost:3000

Global Installation via NPM

npm install -g apidiff-proxy
apidiff --port 8787 --target http://localhost:3000

Programmable Integration in Node.js / Express

import APIDiff from "apidiff-proxy";

const apidiff = new APIDiff({
  port: 8787,
  target: "http://localhost:3000",
});

await apidiff.start();

---

TypeScript Interface Generation

APIDiff automatically converts locked baseline API payload contracts into TypeScript type definitions:

• Dashboard UI: Click Export TypeScript Types (.d.ts) on http://localhost:8787.
• HTTP Endpoint: Download directly via GET http://localhost:8787/_apidiff/api/export/typescript.

Example output:

// Auto-generated by APIDiff
export interface GetUsersResponse {
  email: string;
  id: number;
  is_active: boolean;
  roles: string[];
  score: number;
  username: string;
}

---

Production-Grade Capabilities

1. Low Overhead: Built with Go standard library httputil.NewSingleHostReverseProxy for ultra-low latency transparent proxying.
2. Memory Safety: Uses thread-safe mutex locking (sync.RWMutex) and a bounded ring buffer (500 requests max) to prevent memory leaks under high traffic load.
3. Resilient SSE Streaming: Non-blocking Server-Sent Events hub with drop safety ensures slow dashboard clients don't block API proxy throughput.
4. Single Binary Deployment: Zero runtime dependencies—the full Web Dashboard is compiled into the binary using go:embed.

---

Project Directory Structure

.
├── bin/                 # Node.js CLI executable wrapper (npx support)
├── cmd/
│   └── apidiff/         # Main Go application entry point
├── docs/                # Architectural & schema diff specification docs
├── internal/
│   ├── capture/         # Network traffic payload & header sanitization
│   ├── config/          # Configuration loader
│   ├── contract/        # TypeScript interface generator & contract exports
│   ├── diff/            # Real-time JSON schema diffing engine & tests
│   ├── events/          # Server-Sent Events (SSE) broadcasting hub
│   ├── mock/            # Built-in interactive contract drift simulator
│   ├── proxy/           # HTTP reverse proxy & traffic sniffing interceptor
│   ├── schema/          # Recursive JSON schema inference engine
│   ├── server/          # HTTP server router & REST API controllers
│   └── storage/         # Thread-safe in-memory store & disk persistence
├── pkg/
│   └── types/           # Core domain models (SchemaNode, ContractDiff, etc.)
├── tests/               # End-to-end proxy integration tests
├── web/                 # Web Dashboard single-page app (embedded via go:embed)
├── index.js             # JavaScript/Node.js module export
├── index.d.ts           # TypeScript module declarations
├── package.json         # NPM package metadata
├── CONTRIBUTING.md      # Developer contribution guide
└── LICENSE              # MIT License

---

Architecture

[ Frontend App ]
       │
       ▼
┌────────────────────────────────────────────────────────┐
│ APIDiff Proxy Server (Port 8787)                       │
│                                                        │
│  ├─ Proxy Interceptor  ──>  [ Target API Server ]      │
│  ├─ Schema Engine      ──>  Infer JSON Schema          │
│  ├─ Contract Diff      ──>  Compare vs Baseline        │
│  └─ Storage & SSE Hub  ──>  Broadcast Alerts           │
└────────────────────────────────────────────────────────┘
       │
       ▼
[ Web Dashboard & Diff Viewer ] (http://localhost:8787)

---

Testing

Run the full test suite (including unit tests and end-to-end proxy tests):

go test -v ./...

---

Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for contribution guidelines and development workflow.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.