API Design

API Design

Core Principles

1. Resource-Oriented Design -- Model APIs around resources (nouns), not actions (verbs). Use HTTP methods to express operations on those resources.
2. Consistency -- Apply uniform naming conventions, response structures, error formats, and pagination across every endpoint. Consumers should learn the pattern once and apply it everywhere.
3. Standards Compliance -- Follow established RFCs and specifications (HTTP semantics, RFC 7807 for errors, OpenAPI for documentation). Standards reduce ambiguity and enable tooling.
4. Evolvability -- Design APIs that can grow without breaking existing clients. Use versioning strategies, additive changes, and deprecation policies.
5. Least Surprise -- Endpoints should behave the way experienced developers expect. Status codes, method semantics, and error responses should align with HTTP conventions.

REST Resource Design

Use plural nouns for collections. Nest resources to express ownership. Map CRUD operations to HTTP methods.

# Collection operations
GET    /api/v1/users                  # List users
POST   /api/v1/users                  # Create a user

# Instance operations
GET    /api/v1/users/42               # Get user 42
PUT    /api/v1/users/42               # Replace user 42
PATCH  /api/v1/users/42               # Partially update user 42
DELETE /api/v1/users/42               # Delete user 42

# Nested resources (express ownership)
GET    /api/v1/users/42/orders        # List orders for user 42
POST   /api/v1/users/42/orders        # Create order for user 42
GET    /api/v1/users/42/orders/7      # Get specific order

# Actions as sub-resources (when CRUD doesn't fit)
POST   /api/v1/orders/7/cancel        # Cancel order 7
POST   /api/v1/users/42/verify-email  # Trigger email verification

See rest-conventions.md for: resource naming rules, HTTP method semantics, status code selection, and HATEOAS links.

Request/Response Patterns