rest-api-best-practices

Topics in the source

• REST API Best Practices
• Working Style
• Design Workflow
• Heuristics
• Resource Naming
• HTTP Method Semantics
• Status Code Choice
• Error Format

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. 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. 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 snakecase) and stick to it.

This is an excerpt. Refer to the complete source and its current requirements.