/api-design

name: api-design
description: REST API design best practices. Use when designing APIs, choosing status codes, or creating endpoints.
version: 1.0.0
format: 2025-10-02
triggers:
  - "designing APIs, choosing status codes, or creating endpoints"
updated: 2026-04-25
status: ACTIVE

REST API Design

Endpoint Rules

• **Nouns, not verbs:** `/users` not `/getUsers` — HTTP method is the verb
• **Plural nouns:** `/users`, `/orders` — consistent collections
• **Kebab-case:** `/user-profiles` not `/user_profiles`
• **Max 2 levels nesting:** `/users/{id}/orders` — deeper use query params
• **No trailing slashes, no extensions**

HTTP Methods

| Method | Purpose | Idempotent | |--------|---------|------------| | GET | Retrieve | Yes | | POST | Create | No | | PUT | Replace entire resource | Yes | | PATCH | Partial update | No | | DELETE | Remove | Yes |

Status Codes

| Code | Use When | |------|----------| | 200 | Success with body | | 201 | Resource created (+ Location header) | | 204 | Success, no body (DELETE) | | 400 | Malformed request | | 401 | Not authenticated | | 403 | Authenticated but forbidden | | 404 | Not found | | 409 | Conflict (duplicate) | | 422 | Valid syntax, invalid semantics | | 429 | Rate limited |

Error Format

{"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [], "request_id": "req_..."}}

Key Rules

• Always paginate lists (cursor-based preferred, max page size enforced)
• Never expose sequential IDs — use UUIDs
• Auth credentials in headers, never URLs
• Return 400 for unknown parameters (catch typos)
• Include request_id in every response