SKILL.md
API Design
When to use this skill
- Designing new REST APIs
- Creating GraphQL schemas
- Refactoring API endpoints
- Documenting API specifications
- API versioning strategies
- Defining data models and relationships
Instructions
Step 1: Define API requirements
- Identify resources and entities
- Define relationships between entities
- Specify operations (CRUD, custom actions)
- Plan authentication/authorization
- Consider pagination, filtering, sorting
Step 2: Design REST API
Resource naming:
- Use nouns, not verbs:
/usersnot/getUsers
- Use plural names:
/users/{id}
- Nest resources logically:
/users/{id}/posts
- Keep URLs short and intuitive
HTTP methods:
GET: Retrieve resources (idempotent)
POST: Create new resources
PUT: Replace entire resource
PATCH: Partial update
DELETE: Remove resources (idempotent)
Response codes:
200 OK: Success with response body
201 Created: Resource created successfully
204 No Content: Success with no response body
400 Bad Request: Invalid input
401 Unauthorized: Authentication required
403 Forbidden: No permission
404 Not Found: Resource doesn't exist
409 Conflict: Resource conflict
422 Unprocessable Entity: Validation failed
500 Internal Server Error: Server error
Example REST endpoint:
GET /api/v1/users # List users
GET /api/v1/users/{id} # Get user
POST /api/v1/users # Create user
PUT /api/v1/users/{id} # Update user
PATCH /api/v1/users/{id} # Partial update
DELETE /api/v1/users/{id} # Delete userStep 3: Request/Response format
Request example:
POST /api/v1/users
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}Response example:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}Step 4: Error handling
Error response format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input provided",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}Step 5: Pagination
Query parameters:
GET /api/v1/users?page=2&limit=20&sort=-created_at&filter=role:adminResponse with pagination:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 100,
"pages": 5
},
"links": {
"self": "/api/v1/users?page=2&limit=20",
"first": "/api/v1/users?page=1&limit=20",
"prev": "/api/v1/users?page=1&limit=20",
"next": "/api/v1/users?page=3&limit=20",
"last": "/api/v1/users?page=5&limit=20"
}
}Step 6: Authentication
Options:
- JWT (JSON Web Tokens)
- OAuth 2.0
- API Keys
- Session-based
Example with JWT:
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Step 7: Versioning
URL versioning (recommended):
/api/v1/users
/api/v2/usersHeader versioning:
GET /api/users
Accept: application/vnd.api+json; version=1Step 8: Documentation
Create OpenAPI 3.0 specification:
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
created_at:
type: string
format: date-time
UserCreate:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: emailBest practices
- Consistency: Use consistent naming, structure, and patterns
- Versioning: Always version your APIs from the start
- Security: Implement authentication and authorization
- Validation: Validate all inputs on the server side
- Rate limiting: Protect against abuse
- Caching: Use ETags and Cache-Control headers
- CORS: Configure properly for web clients
- Documentation: Keep docs up-to-date with code
- Testing: Test all endpoints thoroughly
- Monitoring: Log requests and track performance
Common patterns
Filtering:
GET /api/v1/users?role=admin&status=activeSorting:
GET /api/v1/users?sort=-created_at,nameField selection:
GET /api/v1/users?fields=id,name,emailBatch operations:
POST /api/v1/users/batch
{
"operations": [
{"action": "create", "data": {...}},
{"action": "update", "id": 123, "data": {...}}
]
}GraphQL alternative
If REST doesn't fit, consider GraphQL:
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
createdAt: DateTime!
}
type Query {
users(page: Int, limit: Int): [User!]!
user(id: ID!): User
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}