rest-api-design
Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.
When & Why to Use This Skill
This Claude skill provides comprehensive guidance for designing RESTful APIs, ensuring adherence to industry standards for resource naming, HTTP methods, and status codes. It helps developers build consistent, scalable, and developer-friendly interfaces by automating the application of REST conventions and best practices for modern web services.
Use Cases
- New API Development: Establishing a robust resource hierarchy and naming convention for a new microservice or web application.
- API Standardization: Auditing and refactoring existing endpoints to ensure consistent use of HTTP methods and idempotent behavior across a team.
- Error Handling Design: Mapping specific application logic errors to the correct HTTP status codes (e.g., 400, 403, 429) to improve client-side integration and debugging.
- Response Schema Definition: Structuring standardized JSON response formats, including metadata, pagination links, and resource attributes for a better developer experience.
- Documentation Preparation: Generating clear examples of query parameters and collection responses for OpenAPI/Swagger documentation.
| name | rest-api-design |
|---|---|
| description | Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces. |
REST API Design
Design RESTful APIs with proper conventions and developer experience.
Resource Naming
# Good - nouns, plural, hierarchical
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/users
PATCH /api/users/123
DELETE /api/users/123
# Bad - verbs, actions in URL
GET /api/getUsers
POST /api/createUser
POST /api/users/123/delete
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Read resource | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |
Status Codes
| Code | Meaning | Use For |
|---|---|---|
| 200 | OK | Successful GET, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation errors |
| 401 | Unauthorized | Missing auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 429 | Too Many Requests | Rate limited |
Response Format
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"name": "John",
"email": "john@example.com"
}
},
"meta": {
"requestId": "req_abc123"
}
}
Collection Response
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
},
"links": {
"self": "/api/users?page=1",
"next": "/api/users?page=2"
}
}
Query Parameters
GET /api/products?category=electronics # Filtering
GET /api/products?sort=-price,name # Sorting
GET /api/products?page=2&limit=20 # Pagination
GET /api/products?fields=id,name,price # Field selection
Best Practices
- Use nouns for resources, not verbs
- Version API via URL path (
/api/v1/) - Return appropriate status codes
- Include pagination for collections
- Document with OpenAPI/Swagger