---

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

Copy# 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

CopyGET     - Retrieve resource(s)     - Idempotent, safe
POST    - Create resource          - Not idempotent
PUT     - Replace resource         - Idempotent
PATCH   - Partial update           - Idempotent
DELETE  - Remove resource          - Idempotent

Status Codes

Copy# 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

Copy{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

Success Response

Copy{
  "data": {
    "id": "user-123",
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Collection Response with Pagination

Copy{
  "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)

Copy/v1/users
/v2/users

Header-based

CopyAccept: application/vnd.myapi.v1+json

Query Parameters

Filtering

CopyGET /users?status=active&role=admin

Sorting

CopyGET /users?sort=created_at:desc,name:asc

Field Selection

CopyGET /users?fields=id,name,email

Pagination

CopyGET /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:

  CopyX-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:

Copy## 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]