REST API Design Review
By Zara · Published · Updated
Checks a REST API design for resource naming, verb use, pagination, error shape, versioning, and auth, and returns a consistent contract with the fixes needed.
Prompt template
## REST API Design Review Review this API design against one consistent contract. - The API: [textarea: Paste the route list or OpenAPI excerpt] - Consumers: [text: Who calls it and from where] - Existing clients: [toggle: Yes, No] - Areas: [multi: Resource naming, Verbs and status codes, Pagination, Filtering, Error format, Versioning, Authentication, Idempotency] - Auth method: [dropdown: API key, Bearer token, OAuth, Session cookie, None] Read the whole route list before judging any one route, because the main failures are inconsistencies between routes. Resources should be plural nouns with predictable nesting; actions that do not fit should be modelled as a sub-resource or a clear verb endpoint. Check each verb for correct semantics and status codes (201 with a Location on create, 204 on empty success, 409 on conflict, 422 on validation failure). Pick one pagination style, preferably cursor-based for growing data, and apply it everywhere a list can grow. Define one error body with a stable code, a message, and field details. For writes that clients may retry, require an idempotency key. If existing clients depend on the current shape, mark each fix as breaking or safe and propose a versioning path. Return a findings table, then the proposed contract for the five most important routes.