A comprehensive API design review for REST APIs, GraphQL APIs, tRPC routers, and Next.js/Nuxt/SvelteKit API routes. Claude audits every endpoint for naming consistency, correct HTTP method usage, input validation, response shape, authentication, rate limiting, error handling, and documentation gaps — then generates a structured report.
Finds all API routes (App Router, Pages Router, server actions, Express, tRPC, GraphQL), lists every endpoint with method/path/description, identifies auth and serialisation patterns
2 — Naming & URLs
Plural nouns not verbs (/users not /getUsers), consistent kebab-case, hierarchy reflecting ownership, action sub-resources (POST /orders/:id/cancel), consistent ID format, versioning strategy
3 — HTTP methods
GET is read-only and idempotent, POST creates/triggers, PUT replaces, PATCH updates partially, DELETE removes — flags misuse of any method
4 — Request validation
Zod/Joi/Yup schemas present on all endpoints, required vs optional fields clear, query param type coercion, stripUnknown for mass assignment prevention, validation error format returns 400 with structured body
5 — Response design
Correct status codes (201 for creation, 204 for empty deletes), consistent success envelope, consistent error shape, no sensitive data leakage, pagination on list endpoints, unbounded list returns flagged
6 — Auth & authorisation
Auth on every mutating endpoint, resource ownership checks, role checks consistent, public endpoints documented, webhook signature verification
7 — Rate limiting
Auth endpoints, resource-intensive endpoints, public endpoints — presence of limits, correct 429 response with Retry-After, idempotency keys on payment endpoints
8 — Error handling
Unhandled rejections, swallowed errors, stack traces exposed to clients, missing handlers for external API failures
9 — Documentation
OpenAPI/Swagger spec presence, JSDoc on complex endpoints, auth requirements clear, CHANGELOG for breaking changes
