REST API best practices

Use when designing or reviewing HTTP JSON APIs, versioning, errors, and cross-cutting concerns.

URLs and resources

• Use clear, consistent resource-based URLs (nouns, not verbs).
• Version the API to manage breaking changes (/v1, /v2).

HTTP methods and semantics

• Follow HTTP methods correctly (GET, POST, PUT/PATCH, DELETE).
• Return appropriate status codes for every response.
• Aim for idempotency where it matters (PUT, DELETE, safe retries).

Request and response shape