---

name: api-design description: Design clean, consistent REST and GraphQL APIs. Use this skill when creating API endpoints, defining request/response schemas, handling errors, or versioning APIs. Covers REST conventions, status codes, pagination, and API documentation.

API Design Best Practices

This skill provides guidance for designing clean, consistent, and developer-friendly APIs.

When This Skill Applies

• Creating new API endpoints
• Defining request/response schemas
• Handling API errors
• Implementing pagination
• Versioning APIs
• Documenting APIs

REST API Conventions

URL Structure

CopyGET    /users          # List users
POST   /users          # Create user
GET    /users/:id      # Get user
PUT    /users/:id      # Replace user
PATCH  /users/:id      # Update user
DELETE /users/:id      # Delete user

# Nested resources
GET    /users/:id/posts        # User's posts
POST   /users/:id/posts        # Create post for user

# Actions (when CRUD doesn't fit)
POST   /users/:id/verify       # Trigger verification
POST   /orders/:id/cancel      # Cancel order

Naming Rules

• Use nouns, not verbs (/users not /getUsers)
• Use plural nouns (/users not /user)
• Use kebab-case for multi-word resources (/user-profiles)
• Use lowercase only
• Avoid deep nesting (max 2 levels)

HTTP Methods

HTTP Status Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Request/Response Design

Request Body

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

Rules:

• Use camelCase for field names
• Keep flat when possible
• Use ISO 8601 for dates (2024-01-15T10:30:00Z)
• Use enums for fixed values

Response Body

Copy{
  "id": "usr_123",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Rules:

• Include id in responses
• Include timestamps (createdAt, updatedAt)
• Use consistent field naming across endpoints
• Don't expose internal IDs if using UUIDs

Error Handling

Error Response Format

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Include:

• Machine-readable error code
• Human-readable message
• Field-level details for validation errors
• Request ID for debugging (optional)

Error Response Examples

Validation Error (422):

Copy{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}

Not Found (404):

Copy{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

Pagination

Offset-Based (Simple)

CopyGET /users?limit=20&offset=40

Response:

Copy{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 40
  }
}

Cursor-Based (Scalable)

CopyGET /users?limit=20&cursor=eyJpZCI6MTIzfQ

Response:

Copy{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}

Use cursor-based for:

• Large datasets
• Real-time data (items added/removed frequently)
• Infinite scroll UIs

Filtering, Sorting, and Fields

Filtering

CopyGET /users?status=active&role=admin
GET /orders?createdAt[gte]=2024-01-01

Sorting

CopyGET /users?sort=createdAt        # Ascending
GET /users?sort=-createdAt       # Descending
GET /users?sort=lastName,firstName

Field Selection

CopyGET /users?fields=id,name,email

Versioning

URL Path (Recommended)

CopyGET /v1/users
GET /v2/users

Pros: Clear, easy to route, cacheable Cons: URL changes on version bump

Header-Based

CopyGET /users
Accept: application/vnd.api+json; version=2

Pros: Clean URLs Cons: Harder to test, less visible

Authentication

API Keys

CopyAuthorization: Bearer <api-key>
# or
X-API-Key: <api-key>

Use for: Server-to-server, simple integrations

JWT (OAuth 2.0)

CopyAuthorization: Bearer <jwt-token>

Use for: User authentication, mobile apps

Rate Limiting

Include headers in responses:

CopyX-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Return 429 when exceeded:

Copy{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

Documentation

Every endpoint should document:

1. URL and method
2. Description of what it does
3. Authentication required
4. Request parameters (path, query, body)
5. Response format with examples
6. Error responses possible
7. Rate limits if applicable

Use OpenAPI/Swagger for auto-generated docs.

API Design Checklist

• Consistent URL naming (plural, kebab-case)
• Appropriate HTTP methods
• Correct status codes
• Consistent error format
• Pagination for lists
• Authentication documented
• Rate limiting implemented
• Versioning strategy defined
• Request validation
• Response examples in docs