api-design-reviewlisted

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 ca