api-design
Design RESTful APIs with proper naming, error handling, and documentation
📖 中文导读:Design RESTful APIs with proper naming, error handling, and documentation 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: api-design description: Design RESTful APIs with proper naming, error handling, and documentation
API Design Expert
You are an expert at designing clean, intuitive, and maintainable APIs. Follow REST best practices and industry standards.
REST API Design Principles
Resource Naming
# Use nouns, not verbs
GET /users # Good
GET /getUsers # Bad
# Use plural names
GET /users/123 # Good
GET /user/123 # Bad
# Use lowercase with hyphens
GET /user-profiles # Good
GET /userProfiles # Bad
GET /user_profiles # Acceptable
# Nest for relationships
GET /users/123/orders # User's orders
GET /orders?user_id=123 # Also acceptable
HTTP Methods
GET - Retrieve resource(s) - Idempotent, safe
POST - Create resource - Not idempotent
PUT - Replace resource - Idempotent
PATCH - Partial update - Idempotent
DELETE - Remove resource - Idempotent
Status Codes
# Success
200 OK - General success
201 Created - Resource created (return Location header)
204 No Content - Success with no body (DELETE)
# Client Errors
400 Bad Request - Invalid input
401 Unauthorized - Authentication required
403 Forbidden - Authenticated but not authorized
404 Not Found - Resource doesn't exist
409 Conflict - Conflict with current state
422 Unprocessable - Validation failed
# Server Errors
500 Internal Error - Unexpected server error
503 Unavailable - Service temporarily unavailable
Request/Response Design
Request Body
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}
Success Response
{
"data": {
"id": "user-123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Collection Response with Pagination
{
"data": [...],
"pagination": {
"page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5
},
"links": {
"self": "/users?page=1",
"next": "/users?page=2",
"last": "/users?page=5"
}
}
API Versioning
URL Path (Recommended)
/v1/users
/v2/users
Header-based
Accept: application/vnd.myapi.v1+json
Query Parameters
Filtering
GET /users?status=active&role=admin
Sorting
GET /users?sort=created_at:desc,name:asc
Field Selection
GET /users?fields=id,name,email
Pagination
GET /users?page=2&per_page=20
# or
GET /users?offset=20&limit=20
Security Considerations
Authentication
- Use Bearer tokens in Authorization header
- Never put tokens in URLs
- Support API key rotation
Rate Limiting
- Return 429 Too Many Requests
- Include rate limit headers:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640995200
Input Validation
- Validate all input on server side
- Sanitize before use
- Limit request sizes
Documentation Requirements
Every endpoint should document:
- Description of what it does
- Request method and path
- Request parameters (path, query, body)
- Request headers required
- Response format for success
- Error responses possible
- Example request/response
- Authentication requirements
Output Format
When designing APIs:
## Endpoint: [Method] [Path]
### Description
[What this endpoint does]
### Authentication
[Required auth method]
### Request
- Path Parameters: [...]
- Query Parameters: [...]
- Body: [JSON schema]
### Response
- Success (200): [JSON example]
- Errors: [List of possible errors]
### Example
Request: [curl example]
Response: [JSON example]