api-design-review

An API contract is the hardest thing in a codebase to change once someone depends on it. Review it as a future consumer under pressure: every inconsistency you let through becomes a permanent workaround in every client. Ground each finding in the project's existing conventions first; consistency with the API a team already ships beats textbook purity.

Step 1: Establish the existing contract

Before judging anything, learn what this API already does:

• Find the existing routes/resolvers and read three or four representative ones end to end (path, verbs, request/response shapes, error handling).
• Find the conventions: error envelope shape, pagination style, naming case (camelCase vs snake_case), plural vs singular resources, auth mechanism, versioning scheme (path, header, or none).
• Find any OpenAPI/GraphQL schema, API docs, or client SDKs; those are the contract's consumers-eye view.

New surface must match these unless there is a stated reason to diverge, and divergence should be raised as its own finding.

Step 2: Review the surface

Work through the checklist against each new or changed endpoint. Flag only what is wrong or risky, with the concrete revision.

Resources and naming

• Nouns for resources, verbs only via HTTP methods (POST /orders, not POST /createOrder). Sub-resources for ownership (/users/{id}/orders), not query-parameter relationships.
• Consistent casing and pluralization with the rest of the API.

HTTP semantics

• GET is safe and cacheable, never mutates. PUT is full replace and idempotent; PATCH is partial. DELETE is idempotent (second call returns the same outcome, 404 or 204, deliberately chosen).
• Status codes carry meaning: 201 + Location for creation, 400 for malformed input vs 422 for valid-but-unprocessable (pick the project's existing convention), 401 unauthenticated vs 403 unauthorized, 409 for conflicts, 429 with Retry-After for rate limits. Never 200 with an error in the body.

Errors

• One error envelope everywhere, machine-distinguishable (a stable code field, not just prose), with enough detail to act on but no internals (no stack traces, no SQL, no infrastructure hostnames).
• Validation errors name the field that failed.