SKILL.md
API Design
Purpose
Design clear, consistent, and maintainable REST APIs following industry best practices and conventions.
When to Use
- Designing new API endpoints
- Refactoring existing APIs
- Creating integration interfaces
- Planning service-to-service communication
Key Capabilities
- REST Principles - Apply RESTful design patterns correctly
- Resource Modeling - Design clear resource hierarchies
- Error Responses - Define consistent error handling
Approach
- Identify resources and their relationships
- Design URL structure (nouns, not verbs)
- Choose appropriate HTTP methods (GET, POST, PUT, DELETE)
- Design request/response formats
- Plan error handling and status codes
- Document with examples
Example
Context: User profile management API
Design: ``` GET /users/{id} # Get user POST /users # Create user PUT /users/{id} # Update user DELETE /users/{id} # Delete user GET /users/{id}/profile # Get profile PUT /users/{id}/profile # Update profile ```
Best Practices
- ✅ Use nouns for resources, HTTP verbs for actions
- ✅ Consistent URL patterns and naming
- ✅ Proper HTTP status codes (200, 201, 404, 500)
- ❌ Avoid: Verbs in URLs (/getUser, /createUser)