api-design

API Design

Core Principles

• Contract-First — Define API spec before implementation
• OpenAPI 3.2 — Use OpenAPI for REST API documentation
• URL Versioning — Version in path /v1/, with Sunset headers
• Idempotency — PUT/DELETE must be idempotent, POST uses Idempotency-Key
• Cursor Pagination — Avoid offset-based pagination
• RFC 7807 Errors — Standard Problem Details format
• No backwards compatibility — Delete, don't deprecate

Quick Reference

When to Use What

REST API Design

Resource Naming

# Good
GET  /users              # List users
GET  /users/123          # Get user
POST /users              # Create user
PUT  /users/123          # Replace user
PATCH /users/123         # Update user
DELETE /users/123        # Delete user

# Nested resources
GET /users/123/orders    # User's orders

# Actions (when CRUD doesn't fit)
POST /users/123/activate # Action on resource

# Query parameters for filtering
GET /users?status=active&role=admin&limit=20

HTTP Methods

Status Codes

# Success
200 OK              - Successful GET/PUT/PATCH
201 Created         - Successful POST (include Location header)
204 No Content      - Successful DELETE

# Client Errors
400 Bad Request     - Malformed request syntax
401 Unauthorized    - Missing/invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource doesn't exist
409 Conflict        - Duplicate/conflict (e.g., unique constraint)
422 Unprocessable   - Validation failed
429 Too Many        - Rate limited

# Server Errors
500 Internal Error  - Unexpected server error
503 Unavailable     - Service temporarily down