/api-design

name: api-design
description: "REST API design best practices covering versioning, error handling, pagination, and OpenAPI documentation. Use when designing or implementing REST APIs or HTTP endpoints. TRIGGER when: API design, REST endpoint, HTTP route, OpenAPI, swagger, pagination. DO NOT TRIGGER when: internal library code, CLI tools, non-HTTP interfaces."
allowed-tools: [Read]

API Design Skill

REST API design best practices, HTTP conventions, versioning, error handling, and documentation standards.

When This Skill Activates

• Designing REST APIs
• Creating HTTP endpoints
• Writing API documentation
• Handling API errors
• Implementing pagination
• API versioning strategies
• Keywords: "api", "rest", "endpoint", "http", "json", "openapi"

---

Core Concepts

1. REST Principles

RESTful resource design using nouns (not verbs), proper HTTP methods, and hierarchical URL structure.

**Key Principles**:

• Resources are nouns: `/users`, `/posts` (not `/getUsers`, `/createPost`)
• Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
• Hierarchical relationships: `/users/123/posts` for related resources
• Keep URLs shallow (max 3 levels)

**See**: `docs/rest-principles.md` for detailed examples and patterns

---

2. HTTP Status Codes

Proper status code usage for success (2xx), client errors (4xx), and server errors (5xx).

**Common Codes**:

• **200 OK**: Successful GET/PUT/PATCH
• **201 Created**: Successful POST (includes Location header)
• **204 No Content**: Successful DELETE
• **400 Bad Request**: Invalid input
• **401 Unauthorized**: Authentication required
• **403 Forbidden**: Authenticated but not allowed
• **404 Not Found**: Resource doesn't exist
• **422 Unprocessable**: Validation error
• **429 Too Many Requests**: Rate limit exceeded
• **500 Internal Server Error**: Server failure

**See**: `docs/http-status-codes.md` for complete reference and examples

---

3. Error Handling

RFC 7807 Problem Details format for consistent, structured error responses.

**Standard Format**:

{
  "type": "https://example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Email address is invalid",
  "instance": "/users",
  "errors": {
    "email": ["Must be a valid email address"]
  }
}

**See**: `docs/error-handling.md` for implementation patterns and best practices

---

4. Request/Response Format

JSON structure conventions for request bodies and response payloads.

**Best Practices**:

• Use `snake_case` for JSON keys
• Include metadata in responses (timestamps, IDs)
• Consistent field naming across endpoints
• Clear data types and structures

**See**: `docs/request-response-format.md` for detailed examples

---

5. Pagination

Offset-based and cursor-based pagination strategies for large datasets.

**Offset-Based** (simple, good for small datasets):

GET /users?page=2&limit=20

**Cursor-Based** (scalable, handles real-time updates):

GET /users?cursor=abc123&limit=20

**See**: `docs/pagination.md` for implementation details and trade-offs

---

6. API Versioning

URL path versioning (recommended) and header-based versioning strategies.

**URL Path Versioning**:

/v1/users
/v2/users

**When to Version**:

• Breaking changes (removing fields, changing behavior)
• New required fields
• Changed data types

**See**: `docs/versioning.md` for migration strategies and deprecation policies

---

7. Authentication & Authorization

API key and JWT authentication patterns for securing endpoints.

**API Key** (simple, good for service-to-service):

Authorization: Bearer sk_live_abc123...

**JWT** (stateless, good for user authentication):

Authorization: Bearer eyJhbGc...

**See**: `docs/authentication.md` for implementation patterns

---

8. Rate Limiting

Rate limit headers and strategies to prevent abuse.

**Standard Headers**:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

**See**: `docs/rate-limiting.md` for implementation strategies

---

9. Advanced Features

CORS configuration, filtering, sorting, and search patterns.

**Topics**:

• CORS headers for browser-based clients
• Query parameter filtering
• Multi-field sorting
• Full-text search

**See**: `docs/advanced-features.md` for detailed patterns

---

10. Documentation

OpenAPI/Swagger documentation for API discoverability.

**Auto-Generated** (FastAPI):

@app.get("/users/{user_id}", response_model=User)
def get_user(user_id: int):
    """Get user by ID"""
    return db.get_user(user_id)

**See**: `docs/documentation.md` for OpenAPI specifications

---

11. Design Patterns

Idempotency, content negotiation, HATEOAS, bulk operations, and webhooks.

**Topics**:

• Idempotency keys for safe retries
• Content negotiation (JSON, XML, etc.)
• HATEOAS for discoverable APIs
• Bulk operations for batch processing
• Webhooks for event notifications

**See**: `docs/idempotency-content-negotiation.md` and `docs/patterns-checklist.md`

---

Quick Reference

| Pattern | Use Case | Details | |---------|----------|---------| | REST Principles | Resource-based URLs | `docs/rest-principles.md` | | Status Codes | HTTP response codes | `docs/http-status-codes.md` | | Error Handling | RFC 7807 errors | `docs/error-handling.md` | | Pagination | Large datasets | `docs/pagination.md` | | Versioning | Breaking changes | `docs/versioning.md` | | Authentication | API security | `docs/authentication.md` | | Rate Limiting | Abuse prevention | `docs/rate-limiting.md` | | Documentation | OpenAPI/Swagger | `docs/documentation.md` |

---

API Design Checklist

**Before Launch**:

• [ ] Use RESTful resource naming (nouns, not verbs)
• [ ] Implement proper HTTP status codes
• [ ] Add RFC 7807 error responses
• [ ] Include pagination for collections
• [ ] Add API versioning strategy
• [ ] Implement authent