api-design
This skill should be used for REST API, GraphQL, versioning, pagination, authentication, backend routes, web services, HTTP endpoints, server API design
When & Why to Use This Skill
This Claude skill provides comprehensive guidance and industry best practices for designing robust, scalable, and standardized RESTful APIs and GraphQL services. It covers essential architectural patterns including URL structuring, versioning strategies, pagination implementation, and standardized error handling to ensure high-quality backend development and seamless integration.
Use Cases
- Architecting new RESTful APIs with standardized resource naming and intuitive URL structures for better developer experience.
- Implementing API versioning strategies (URL or Header-based) to manage breaking changes and maintain backward compatibility.
- Designing consistent pagination and metadata schemas for large datasets to optimize web service performance.
- Defining standardized error response formats and selecting appropriate HTTP status codes to improve client-side debugging and reliability.
- Developing secure backend routes and authentication flows for modern web services and microservices.
| name | api-design |
|---|---|
| description | This skill should be used for REST API, GraphQL, versioning, pagination, authentication, backend routes, web services, HTTP endpoints, server API design |
| whenToUse | API design, endpoints, REST patterns, backend development, web services, HTTP routes, server-side endpoints, Express routes, FastAPI endpoints |
| whenNotToUse | Internal interfaces, non-HTTP APIs, frontend-only code |
| - skill | database-patterns |
| when | API data modeling |
API Design
REST API design best practices.
URL Structure
GET /users # List
GET /users/:id # Get one
POST /users # Create
PUT /users/:id # Replace
PATCH /users/:id # Update
DELETE /users/:id # Delete
Versioning
/api/v1/users # URL versioning
Accept: application/vnd.api.v1+json # Header
Pagination
{
"data": [...],
"pagination": {
"page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5
}
}
Error Responses
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"details": [{"field": "email", "issue": "invalid format"}]
}
}
Status Codes
| Code | Use |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Server error |