REST API Design Reviewer

---
name: api-design
description: REST API design conventions. Use when adding or modifying HTTP endpoints.
---

# REST API Design Reviewer

Apply these conventions to every endpoint added or changed.

## Naming

- Plural nouns for collections: `/users`, `/users/{id}/orders`
- No verbs in paths — the method is the verb. `POST /orders`, never `/createOrder`
- kebab-case for multi-word resources: `/payment-methods`
- Nesting max 2 levels deep; beyond that, use filters: `/orders?customer_id=X`

## Status codes (exact usage)

- 200 read/update success · 201 created (with Location header) · 204 delete success
- 400 malformed request · 401 unauthenticated · 403 unauthorized · 404 not found
- 409 conflict (duplicate, version clash) · 422 validation failure with field errors
- Never 200 with `{"error": ...}` in the body

## Error envelope (all non-2xx)

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Human-readable summary",
    "details": [{"field": "email", "issue": "invalid format"}]
  }
}
```

## Collections

- Always paginated: `?cursor=` preferred, `?page=&limit=` acceptable; default limit 25, max 100
- Response shape: `{"data": [...], "pagination": {"next_cursor": ...}}`
- Filtering via query params matching field names; sorting via `?sort=-created_at`

## Change safety

- Breaking changes (removed fields, changed types, new required params) require a new version or explicit sign-off — flag them, never ship silently
- New fields in responses are safe; document them
- Match the existing codebase's auth middleware pattern — never hand-roll auth on a new route

How to use

1. 1Save as .claude/skills/api-design/SKILL.md and adjust conventions to your existing API (don't create a second style).
2. 2Applied automatically when the agent touches routes/controllers.
3. 3For an existing inconsistent API: document your dominant style here and let consistency win over ideal REST.

Examples

Pro tips

• The 'never 200 with an error body' rule alone prevents the most painful client-side debugging sessions.