api-designlisted

# API Design Skill REST API design best practices, HTTP conventions, versioning, error handling, and documentation standards. ## When This Skill Activates - Designing REST APIs - Creating HTTP endpoints - Writing API documentation - Handling API errors - Implementing pagination - API versioning strategies - Keywords: "api", "rest", "endpoint", "http", "json", "openapi" --- ## Core Concepts ### 1. REST Principles RESTful resource design using nouns (not verbs), proper HTTP methods, and hierarchical URL structure. **Key Principles**: - Resources are nouns: `/users`, `/posts` (not `/getUsers`, `/createPost`) - Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove) - Hierarchical relationships: `/users/123/posts` for related resources - Keep URLs shallow (max 3 levels) **See**: `docs/rest-principles.md` for detailed examples and patterns --- ### 2. HTTP Status Codes Proper status code usage for success (2xx), client errors (4xx), and server errors (5xx). **Common Codes**: - **200 OK**: Successful GET/PUT/PATCH - **201 Created**: Successful POST (includes Location header) - **204 No Content**: Successful DELETE - **400 Bad Request**: Invalid input - **401 Unauthorized**: Authentication required - **403 Forbidden**: Authenticated but not allowed - **404 Not Found**: Resource doesn't exist - **422 Unprocessable**: Validation error - **429 Too Many Requests**: Rate limit exceeded - **500 Internal Server Error**: Server failu