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-02T00:00:00.000Z"
triggers	["designing APIs, choosing status codes, or creating endpoints"]
updated	"2026-04-25T00:00:00.000Z"
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