---
name: rest-api-design-review
description: "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. Use when a REST API design or OpenAPI draft needs a review of naming, status codes, pagination, error format, versioning, and auth before clients depend on it. Do not use for implementing the endpoints or designing a GraphQL schema. Related topics: coding, technical."
---

# REST API Design Review

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.

## When to use

Use this skill when a REST API design or OpenAPI draft needs a review of naming, status codes, pagination, error format, versioning, and auth before clients depend on it. Do not use it for implementing the endpoints or designing a GraphQL schema.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Read the full route list and write down the patterns in use for naming, nesting, pagination, and errors.
3. Check each route's verb, status codes, and idempotency against those patterns and against HTTP semantics.
4. Define the single pagination style and single error body the whole API should use.
5. Mark every proposed change as breaking or safe for existing clients and sketch a versioning path for the breaking ones.
6. Return a findings table and the proposed contract for the five most important routes.

## Inputs

- **The API** (longer free text)
- **Consumers** (free text, e.g. "Who calls it and from where")
- **Existing clients** (choose one: Yes, No)
- **Areas** (choose any: Resource naming, Verbs and status codes, Pagination, Filtering, Error format, Versioning, Authentication, Idempotency)
- **Auth method** (choose one: API key, Bearer token, OAuth, Session cookie, None)

## Output

A findings table with route, issue, fix, and breaking or safe, followed by the proposed contract for the five most important routes.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### REST API Design Review

Review this API design against one consistent contract.

- The API: {{The API}}
- Consumers: {{Consumers}}
- Existing clients: {{Existing clients}}
- Areas: {{Areas}}
- Auth method: {{Auth method}}

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.

## Pitfalls

- Reviewing routes one at a time and missing that three of them paginate in different ways.
- Using 200 with an error body for failures, which breaks every client that trusts status codes.
- Proposing a clean rename without checking it is a breaking change for live clients.