API Contract Guardian
A developer tool that validates API responses against their TypeScript type definitions at runtime, catching contract drift before it ships.
01. Overview
Built a tool that bridges the gap between TypeScript's compile-time checks and runtime API behavior. It intercepts API responses and validates them against declared TypeScript interfaces, flagging any drift between what the API says it returns and what it actually returns.
02. Problem Statement
Silent Contract Drift
In full-stack TypeScript projects, the backend API types and frontend consumption types often drift apart silently. TypeScript only checks at compile time — if the API starts returning a different shape at runtime, the frontend breaks with cryptic errors that are hard to trace back to the API change.
03. Constraints
- 01Non-Invasive IntegrationMust integrate into existing projects without requiring changes to API route implementations.
- 02Development OnlyValidation overhead must be zero in production — the tool runs only in development builds.
04. System Architecture
Interceptor
Express middleware that captures API responses before they reach the client.
Schema Generator
Converts TypeScript interface declarations into runtime-checkable JSON schemas.
Reporter
Logs mismatches with diff-style output showing expected vs actual shapes.
05. Key Decisions
GitHub OAuth for Team Features
Integrated GitHub authentication to support team-level contract monitoring and shared validation dashboards.
06. Trade-Offs
Development-Only Scope
Choosing to make this dev-only reduced complexity but means production API drift is still caught only by monitoring, not prevention.
07. Outcome
The tool catches contract drift within seconds of an API change during development, preventing broken deployments and reducing frontend debugging from hours to minutes.