diegosouzapw API Design Evaluator
Evaluate API design output against these criteria.
RESTfulness (25%)
- Are HTTP methods used correctly (GET for reads, POST for creation, PUT/PATCH for updates, DELETE for removal)?
- Are resource URLs noun-based and plural (/users, /orders, not /getUsers, /createOrder)?
- Are status codes appropriate (201 for creation, 204 for no content, 404 for not found)?
- Is the URL hierarchy logical (/users/:id/orders, not /user-orders)?
- Are query parameters used for filtering/sorting/pagination (not path segments)?
- Is HATEOAS considered where appropriate?
- For non-REST APIs (GraphQL, RPC): are equivalent conventions followed?
Consistency (25%)
- Are naming conventions consistent (camelCase vs snake_case, chosen and stuck to)?
- Are response shapes consistent across endpoints (same envelope, same error format)?
- Are pagination patterns consistent (cursor vs offset, same parameter names)?
- Do similar operations behave similarly (all CRUD endpoints for all resources follow same pattern)?
- Are date formats consistent (ISO 8601)?
- Are ID formats consistent (UUID vs integer, same field name)?
Error Responses (30%)
- Do error responses include a machine-readable error code?
- Do error responses include a human-readable message?
- Are validation errors specific (which field failed, why)?
- Are errors safe (no stack traces, internal paths, or SQL in production responses)?
- Are error codes documented and stable (clients can switch on them)?
- Is there a consistent error envelope (same shape for all errors)?
- Are rate limit errors informative (retry-after header)?
- Do 5xx responses avoid leaking implementation details?
Documentation (20%)
- Are request/response schemas defined (OpenAPI, JSON Schema, or equivalent)?
- Are required vs optional fields clearly marked?
- Are example requests and responses provided?
- Are authentication requirements documented per endpoint?
- Are rate limits and quotas documented?
- Are breaking change policies documented (versioning strategy)?
- Is the documentation generated from code or kept in sync?
Severity Guide
- Blocker: Wrong HTTP method semantics, error responses leaking internals, missing auth on sensitive endpoint
- Important: Inconsistent naming across endpoints, missing error codes, no pagination on list endpoints
- Suggestion: Minor naming improvements, additional examples, HATEOAS links