| name | API Design |
| description | Design RESTful APIs with proper resource modeling, HTTP methods, error handling, and clear contracts following REST principles |
| category | architecture |
| required_tools | ["Read","Write","WebSearch"] |
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)
