api-design-audit

API Design Audit

Overview

APIs are contracts. Breaking changes break trust. Bad design creates permanent technical debt that every consumer inherits.

Core principle: Design APIs for the consumer, not the implementation. The best API is the one nobody needs documentation to understand.

The Iron Law

NO API ENDPOINT WITHOUT DEFINED CONTRACT, ERROR HANDLING, VALIDATION, AND DOCUMENTATION. NO BREAKING CHANGE WITHOUT VERSIONING.

When to Use

• Designing new API endpoints
• Reviewing existing API architecture
• Investigating API-related bugs
• Before publishing or versioning an API
• When consumers report confusing behavior
• During any codebase audit

When NOT to Use

• Internal function interfaces (use code-review or architecture-audit)
• Database query optimization (use database-audit)
• UI form validation only (use frontend-audit)

Anti-Shortcut Rules

YOU CANNOT:
- Say "API looks standard" — check every endpoint against REST conventions or chosen style
- Say "errors are handled" — verify every endpoint returns structured errors with correct HTTP status
- Say "inputs are validated" — test boundaries, missing fields, wrong types, malicious input
- Skip pagination check — verify every list endpoint is paginated with limits
- Say "auth is fine" — verify every endpoint enforces auth AND authorization (ownership)
- Skip response shape consistency — compare 5+ endpoint responses for structural consistency
- Say "documentation exists" — verify docs match actual behavior (test one endpoint against docs)
- Trust error messages — verify they're helpful but don't leak internals (no stack traces, no SQL)

Common Rationalizations (Don't Accept These)

Rationalization	Reality
"It's an internal API, it doesn't need docs"	Internal APIs become external. Undocumented APIs break silently.
"We'll add pagination later"	By then, someone's written a client that expects all results. Breaking change.
"Validation is done on the frontend"	Frontend validation is UX. Backend validation is security. Both are required.
"We don't need versioning yet"	By the time you need it, you have consumers who can't handle the breaking change.
"Our error messages are fine"	"Internal server error" is not fine. "Email must be a valid email address" is fine.
"Rate limiting is overkill"	One script without rate limiting can take down your API in seconds.
"We use the same response format everywhere"	Verify it. "Everywhere" often has exceptions nobody remembers.