API Design Review

Review the API design (routes, schemas, OpenAPI spec, or code) for consistency, correctness, and developer experience.

REST conventions

• HTTP methods used correctly (GET reads, POST creates, PUT/PATCH updates, DELETE removes)
• Status codes accurate (201 for create, 204 for empty success, 422 for validation errors)
• Resource naming: plural nouns, kebab-case (/user-profiles, not /getUserProfile)
• No verbs in URLs — actions belong in the method

Consistency

• Naming convention uniform (camelCase vs snake_case — pick one)
• Error response format the same across all endpoints
• Pagination, filtering, and sorting follow the same pattern
• Timestamps in ISO 8601

Design gaps

• Missing endpoints that callers will obviously need
• Redundant endpoints doing the same thing
• Overly chatty (requires too many calls to do one task)

Security

• Auth required where it should be
• No sensitive data in query params (use headers or body)
• Rate limiting considerations
• CORS policy intentional, not wildcard

Versioning

• Strategy is clear (/v1/, header, or content negotiation)
• Breaking vs non-breaking changes identified

Output

Prioritized list of issues with: what's wrong, why it matters, and the suggested fix.