rest-api-best-practices

REST API Best Practices

Use this skill when the main question is how to design, review, or improve a REST API — from URL structure to error formats to security.

Working Style

1. Start from what the consumer needs, not from what the database looks like.
2. Use HTTP as designed — methods, status codes, and headers carry meaning.
3. Express domain capabilities, not data operations.
4. Make errors as informative as successes.
5. Design for change: version early, break compatibility deliberately.

Design Workflow

1. Define the resources.

   • What are the concepts the consumer needs to interact with?
   • Name them with nouns, in plural form.
   • Avoid verbs in URLs — the HTTP method is the verb.

2. Choose the right HTTP method.

   • GET for retrieval (safe, idempotent, cacheable)
   • POST for creation or non-idempotent operations
   • PUT for full replacement (idempotent)
   • PATCH for partial update
   • DELETE for removal (idempotent)

3. Design the URL.

   • Keep paths flat where possible — at most two levels of nesting.
   • Use query parameters for filtering, sorting, and pagination.
   • Use task URLs (POST /orders/{id}/cancel) for domain operations that aren't simple CRUD.

4. Define response shapes.

   • Choose a consistent field naming convention (camelCase or snake_case) and stick to it.
   • Return only what the consumer needs.
   • Use HTTP headers for metadata (pagination, rate limits).

5. Define error responses.

   • Use the right 4xx or 5xx status code — never return 200 for errors.
   • Return a structured error body with a machine-readable code and a human-readable message.
   • Follow RFC 9457 (Problem Details, which obsoletes RFC 7807) when the team needs a standard.

6. Add versioning.

   • Default to URL versioning (/v1/).
   • Treat a breaking change as a reason to bump the version, not to patch silently.

Heuristics

Resource Naming

Nouns, plural, lowercase, kebab-case for multi-word: /user-profiles, /order-items.