Agent skill
api-design
Design RESTful APIs with proper naming, error handling, and documentation
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/api-design-arthur742ramos-azure-codex
SKILL.md
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
json
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}
Success Response
json
{
"data": {
"id": "user-123",
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
}
Error Response
json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Collection Response with Pagination
json
{
"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]
Didn't find tool you were looking for?