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:

json

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

bash

GET /users?page=2&limit=20

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

bash

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:

bash

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

http

Authorization: Bearer sk_live_abc123...

JWT (stateless, good for user authentication):

http

Authorization: Bearer eyJhbGc...

See: docs/authentication.md for implementation patterns

8. Rate Limiting

Rate limit headers and strategies to prevent abuse.

Standard Headers:

http

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

python

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

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

•Resources are nouns: /users, not /getUsers
•Use HTTP methods correctly: GET (read), POST (create), PUT (replace), DELETE (remove)
•Return proper status codes: 200 (success), 201 (created), 404 (not found), 422 (validation error)
•Structured errors: Use RFC 7807 format
•Paginate collections: Offset or cursor-based
•Version your API: URL path versioning (e.g., /v1/users)
•Secure endpoints: API keys or JWT
•Rate limit: Prevent abuse
•Document thoroughly: OpenAPI/Swagger
•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