api-design-restlisted

# RESTful API Design ## Purpose REST APIs MUST be intuitive, predictable, and semantically correct. This skill ensures APIs use HTTP methods correctly, communicate errors clearly via standard formats, and maintain consistency across resources so clients can interact with them reliably without surprise behavior. ## When to use - Building a new backend service exposing resources - Adding a new domain entity to an existing API - Creating integration endpoints for third-party partners - Designing webhooks or callback mechanisms - Standardizing an inconsistent API across a microservices architecture ## When NOT to use - Error handling specifics (use Error Handling Architecture skill) - API authentication/authorization (separate concern) - Rate limiting or throttling strategies (separate concern) - GraphQL design (different paradigm) ## Inputs required - Existing API codebase or documented business entities - HTTP framework (Express, Django, FastAPI, etc.) - OpenAPI/Swagger familiarity preferred ## Workflow 1. **Identify Resources**: Map business entities to Plural Nouns (users, orders, invoices, not getUsers) 2. **Assign Verbs**: Map CRUD operations to HTTP methods: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove) 3. **Design URL Hierarchy**: Nest resources logically but NO DEEPER than 2 levels (e.g., `/users/{id}/orders` ONLY) 4. **Standardize Responses**: All success payloads wrapped consistently; all errors use RFC 7807 format 5. **Add Pagination**