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

/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]