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 authentication
• Add rate limiting
• Configure CORS (if browser clients)
• Generate OpenAPI documentation
• Test idempotency for POST/PUT/DELETE

See: docs/patterns-checklist.md for complete checklist

---

Progressive Disclosure

This skill uses progressive disclosure to prevent context bloat:

• Index (this file): High-level concepts and quick reference (<500 lines)
• Detailed docs: docs/*.md files with implementation details (loaded on-demand)

Available Documentation:

• docs/rest-principles.md - RESTful design patterns
• docs/http-status-codes.md - Complete status code reference
• docs/error-handling.md - Error response patterns
• docs/request-response-format.md - JSON structure conventions
• docs/pagination.md - Pagination strategies
• docs/versioning.md - API versioning patterns
• docs/authentication.md - Authentication methods
• docs/rate-limiting.md - Rate limiting implementation
• docs/advanced-features.md - CORS, filtering, sorting
• docs/documentation.md - OpenAPI/Swagger
• docs/idempotency-content-negotiation.md - Advanced patterns
• docs/patterns-checklist.md - Design checklist and common patterns

---

Cross-References

Related Skills:

• error-handling-patterns - Error handling best practices
• security-patterns - API security hardening
• python-standards - Python API implementation and documentation standards

Related Libraries:

• FastAPI - Python API framework with auto-documentation
• Pydantic - Data validation and serialization
• JWT libraries - Token-based authentication

---

Key Takeaways

1. Resources are nouns: /users, not /getUsers
2. Use HTTP methods correctly: GET (read), POST (create), PUT (replace), DELETE (remove)
3. Return proper status codes: 200 (success), 201 (created), 404 (not found), 422 (validation error)
4. Structured errors: Use RFC 7807 format
5. Paginate collections: Offset or cursor-based
6. Version your API: URL path versioning (e.g., /v1/users)
7. Secure endpoints: API keys or JWT
8. Rate limit: Prevent abuse
9. Document thoroughly: OpenAPI/Swagger
10. Test idempotency: Safe retries for POST/PUT/DELETE

---

Hard Rules

FORBIDDEN:

• Exposing internal IDs or database schema in API responses
• Returning 200 for error conditions (use proper HTTP status codes)
• APIs without versioning (MUST use URL path versioning like /v1/)
• Endpoints that accept unbounded input without pagination or limits

REQUIRED:

• All endpoints MUST have consistent error response format ({error, message, code})
• All collection endpoints MUST support pagination
• All mutations MUST be idempotent or explicitly documented as non-idempotent
• Rate limiting MUST be documented in API specification