api-design
RESTful API design best practices and conventions guide
When & Why to Use This Skill
This Claude skill provides a comprehensive guide for designing RESTful APIs, offering expert guidance on resource-oriented design, HTTP method implementation, and standardized response formats to build scalable and maintainable web services.
Use Cases
- API Architecture Planning: Designing clean and intuitive URL structures and resource hierarchies for new software projects.
- Standardizing Development: Establishing consistent naming conventions, camelCase field usage, and unified error handling across engineering teams.
- Documentation and Compliance: Ensuring API designs align with industry standards like OpenAPI/Swagger and implement correct HTTP status codes for better client-side integration.
| name | api-design |
|---|---|
| description | RESTful API design best practices and conventions guide |
API Design Skill
This skill provides comprehensive guidance for designing RESTful APIs following industry best practices.
Core Principles
1. Resource-Oriented Design
- Use nouns for resource names (e.g.,
/users,/products) - Avoid verbs in URLs
- Use HTTP methods to represent actions
2. HTTP Methods
- GET: Retrieve resources
- POST: Create new resources
- PUT: Update entire resources
- PATCH: Partial updates
- DELETE: Remove resources
3. URL Structure
GET /api/v1/users - List all users
GET /api/v1/users/{id} - Get specific user
POST /api/v1/users - Create new user
PUT /api/v1/users/{id} - Update user
DELETE /api/v1/users/{id} - Delete user
4. Response Format
- Use JSON as default format
- Use camelCase for field names
- Include metadata (pagination, timestamps)
5. Error Handling
{
"error": {
"code": "INVALID_REQUEST",
"message": "User ID must be a positive integer",
"details": []
}
}
6. Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Internal Server Error
Best Practices
- Version your APIs
- Use pagination for list endpoints
- Implement rate limiting
- Document with OpenAPI/Swagger