API Design Review
Your job is to catch API mistakes while they're still cheap to fix. Once an endpoint has clients, every mistake is a migration.
Related: this skill critiques a new or changed endpoint's design (shape, auth, pagination, error format). For detecting breaking changes to an existing public API (removed fields, renamed fields, narrowed types), use the api-contract-guardian agent instead.
Step 1 — Find the endpoint(s)
- If the user named a file or route, start there.
- Else look at
git diff for added/changed route handlers, OpenAPI/Swagger files, GraphQL schemas, or RPC definitions.
- Read the handler body AND any schema/DTO/validator it references.
If multiple endpoints are in scope, review them one at a time.
Step 2 — Rubric
Walk this in order. Flag each issue as blocker / suggestion / nit.
Contract
- Is the URL shape RESTful and predictable?
/users/:id/orders, not /getUserOrders?id=….
- Is the HTTP method right?
GET reads, POST creates, PUT/PATCH update, DELETE deletes. No GET with side effects.
- Are path params vs. query params used sensibly? Identity → path. Filtering → query.
- Is the request body schema explicit and validated? Missing validation is a security issue, not just an ergonomics issue.
Response shape
- Is the success shape consistent with other endpoints in this service? Envelope vs. bare object — pick one and match.
- Are timestamps ISO 8601 with timezone? Not epoch ints unless the rest of the API uses them.
- Are IDs returned as strings? (Large ints lose precision in JS.)
- Are nullable fields explicit, not omitted-when-null?
Error shape
- Are errors structured (
{ error: { code, message, details } }) or just string messages? Structured wins — clients can branch on code.
- Are HTTP status codes correct? 400 for bad input, 401 for missing auth, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for semantic validation. Don't return 200 with
{ error: ... }.
- Does the error message leak internals? Stack traces, SQL, file paths — all leaks.
Pagination
- Any list endpoint without pagination is a bug waiting to happen. Say so.
- Cursor pagination > offset pagination for anything that changes. Offset skips/duplicates on writes.
- Is the page size capped server-side?
?limit=1000000 should be rejected or clamped.
Auth & authz
- Who can call this? Is that enforced in the handler or assumed?
- Does authz happen before the expensive work (DB query, external call)?
- If the endpoint returns user data, does it check that the caller is allowed to see that user's data — not just "is authenticated"?
- Rate limits: is there one? Public endpoints without rate limits are DoS-by-accident waiting to happen.
Versioning & compatibility
- If this changes an existing endpoint: is the change backwards compatible? Added fields = usually safe. Removed fields, renamed fields, changed types = breaking.
- How will clients know to migrate? Version in URL (
/v2/), header, or content negotiation — whatever the rest of the API does.
Idempotency
- Is the operation idempotent? If not, does it support an idempotency key (for
POST/PATCH)? Network retries on non-idempotent writes = double-charged customers.
Performance
- Does this endpoint do N+1 queries? (Loop over items, query per item.)
- Is the response size bounded? An endpoint that returns "all user's orders" with no pagination is a landmine.
Step 3 — Output
## Summary
One line: endpoint, method, what it does, and your take (ship / fix first / discuss).
## Blockers
Issues that must be fixed before this ships to real clients.
Each: what's wrong — why it matters — suggested fix.
## Suggestions
Should do but won't break anything.
## Nits
Naming, consistency, minor shape cleanups.
## What's good
1–2 specific things done well.
Rules
- Match the existing API style over theoretical purity. A second endpoint that disagrees with the first is worse than two that are both slightly off.
- Always ask about pagination on any list endpoint. Always.
- Call out breaking changes loudly. "This breaks existing clients" is a blocker unless there's a versioning story.
- Don't lecture on REST philosophy. Catch real problems.
1---2name: api-design3description: This skill should be used when the user types /api-design, is adding or changing an HTTP or RPC endpoint, or asks for a review of an API surface before it ships.4---56# API Design Review78Your job is to catch API mistakes while they're still cheap to fix. Once an endpoint has clients, every mistake is a migration.910> **Related:** this skill critiques a *new or changed endpoint's design* (shape, auth, pagination, error format). For detecting *breaking changes to an existing public API* (removed fields, renamed fields, narrowed types), use the `api-contract-guardian` agent instead.1112## Step 1 — Find the endpoint(s)1314- If the user named a file or route, start there.15- Else look at `git diff` for added/changed route handlers, OpenAPI/Swagger files, GraphQL schemas, or RPC definitions.16- Read the handler body AND any schema/DTO/validator it references.1718If multiple endpoints are in scope, review them one at a time.1920## Step 2 — Rubric2122Walk this in order. Flag each issue as blocker / suggestion / nit.2324### Contract2526- Is the URL shape RESTful and predictable? `/users/:id/orders`, not `/getUserOrders?id=…`.27- Is the HTTP method right? `GET` reads, `POST` creates, `PUT`/`PATCH` update, `DELETE` deletes. No `GET` with side effects.28- Are path params vs. query params used sensibly? Identity → path. Filtering → query.29- Is the request body schema explicit and validated? Missing validation is a security issue, not just an ergonomics issue.3031### Response shape3233- Is the success shape consistent with other endpoints in this service? Envelope vs. bare object — pick one and match.34- Are timestamps ISO 8601 with timezone? Not epoch ints unless the rest of the API uses them.35- Are IDs returned as strings? (Large ints lose precision in JS.)36- Are nullable fields explicit, not omitted-when-null?3738### Error shape3940- Are errors structured (`{ error: { code, message, details } }`) or just string messages? Structured wins — clients can branch on `code`.41- Are HTTP status codes correct? 400 for bad input, 401 for missing auth, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for semantic validation. Don't return 200 with `{ error: ... }`.42- Does the error message leak internals? Stack traces, SQL, file paths — all leaks.4344### Pagination4546- Any list endpoint without pagination is a bug waiting to happen. Say so.47- Cursor pagination > offset pagination for anything that changes. Offset skips/duplicates on writes.48- Is the page size capped server-side? `?limit=1000000` should be rejected or clamped.4950### Auth & authz5152- Who can call this? Is that enforced in the handler or assumed?53- Does authz happen *before* the expensive work (DB query, external call)?54- If the endpoint returns user data, does it check that the caller is allowed to see *that* user's data — not just "is authenticated"?55- Rate limits: is there one? Public endpoints without rate limits are DoS-by-accident waiting to happen.5657### Versioning & compatibility5859- If this changes an existing endpoint: is the change backwards compatible? Added fields = usually safe. Removed fields, renamed fields, changed types = breaking.60- How will clients know to migrate? Version in URL (`/v2/`), header, or content negotiation — whatever the rest of the API does.6162### Idempotency6364- Is the operation idempotent? If not, does it support an idempotency key (for `POST`/`PATCH`)? Network retries on non-idempotent writes = double-charged customers.6566### Performance6768- Does this endpoint do N+1 queries? (Loop over items, query per item.)69- Is the response size bounded? An endpoint that returns "all user's orders" with no pagination is a landmine.7071## Step 3 — Output7273```74## Summary75One line: endpoint, method, what it does, and your take (ship / fix first / discuss).7677## Blockers78Issues that must be fixed before this ships to real clients.79Each: what's wrong — why it matters — suggested fix.8081## Suggestions82Should do but won't break anything.8384## Nits85Naming, consistency, minor shape cleanups.8687## What's good881–2 specific things done well.89```9091## Rules9293- **Match the existing API style** over theoretical purity. A second endpoint that disagrees with the first is worse than two that are both slightly off.94- **Always ask about pagination** on any list endpoint. Always.95- **Call out breaking changes loudly.** "This breaks existing clients" is a blocker unless there's a versioning story.96- **Don't lecture on REST philosophy.** Catch real problems.
utsabpanta