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

Status Codes

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