REST API Design

Resource Naming & HTTP Methods

# Use nouns (not verbs), plural, lowercase, hyphens
GET    /users              # list users
POST   /users              # create user
GET    /users/{id}         # get user
PUT    /users/{id}         # replace user (full update)
PATCH  /users/{id}         # partial update
DELETE /users/{id}         # delete user

# Nested resources
GET    /users/{id}/posts           # user's posts
POST   /users/{id}/posts           # create post for user
GET    /users/{id}/posts/{postId}  # specific post

# Actions that don't fit CRUD (use nouns when possible)
POST   /orders/{id}/cancel          # good
POST   /orders/{id}/cancellations   # RESTful noun variant
GET    /search?q=query&type=user    # search

# Don't use verbs in paths
# BAD:  POST /createUser, GET /getUser, POST /users/delete/{id}
# GOOD: POST /users,       GET /users/{id}, DELETE /users/{id}

HTTP Status Codes

# 2xx — Success
200 OK             — GET, PUT, PATCH responses
201 Created        — POST response; include Location: /users/{newId} header
204 No Content     — DELETE, or PATCH with no body response

# 3xx — Redirection
301 Moved Permanently   — permanent URL change
302 Found / 307 Temp    — temporary redirect
304 Not Modified        — ETag/If-None-Match cache hit

# 4xx — Client errors
400 Bad Request         — malformed request, validation failure
401 Unauthorized        — not authenticated (missing/invalid token)
403 Forbidden           — authenticated but not authorized
404 Not Found           — resource doesn't exist
405 Method Not Allowed  — wrong HTTP method for this endpoint
409 Conflict            — duplicate (unique constraint), optimistic lock conflict
410 Gone               — permanently deleted (vs 404 = never existed)
422 Unprocessable       — validation errors on valid JSON
429 Too Many Requests   — rate limited; include Retry-After header

# 5xx — Server errors
500 Internal Server Error  — unexpected error (never expose details)
502 Bad Gateway            — upstream service failed
503 Service Unavailable    — overloaded/down; include Retry-After header

Response Format

// Success — single resource
{
  "id": "usr_123",
  "email": "alice@example.com",
  "name": "Alice",
  "role": "user",
  "createdAt": "2024-01-15T10:30:00Z"
}

// Success — list with pagination
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 143,
    "totalPages": 8,
    "hasNextPage": true,
    "nextCursor": "eyJpZCI6MTIzfQ=="
  }
}

// Error response — consistent shape
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "password", "message": "Must be at least 8 characters" }
    ],
    "requestId": "req_abc123"
  }
}

Headers & Versioning

# Request headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
X-Request-ID: client-generated-uuid
If-None-Match: "abc123"          # conditional GET (ETag)
If-Match: "abc123"               # optimistic concurrency check

# Response headers
Content-Type: application/json; charset=utf-8
X-Request-ID: req_abc123         # echo back for tracing
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1700000000
ETag: "abc123"                   # for caching
Location: /users/123             # after 201 Created
Retry-After: 60                  # after 429 or 503

# API Versioning strategies
# 1. URL path (most common, explicit)
GET /v1/users
GET /v2/users

# 2. Query parameter
GET /users?version=2

# 3. Header (cleanest, least visible)
Accept: application/vnd.api.v2+json
API-Version: 2

# Prefer URL versioning for public APIs — visible and cacheable

Filtering, Sorting & Pagination

# Filtering
GET /users?role=admin&isActive=true
GET /users?age_gte=18&age_lte=65
GET /posts?status=published&tag=javascript

# Sorting
GET /users?sort=name                 # ascending
GET /users?sort=-createdAt           # descending (minus prefix)
GET /users?sort=-createdAt,name      # multiple fields

# Field selection (sparse fieldsets)
GET /users?fields=id,name,email

# Pagination — offset
GET /users?page=2&limit=20

# Pagination — cursor (better for large datasets)
GET /users?cursor=eyJpZCI6MTIzfQ==&limit=20
# Response includes nextCursor for subsequent request

# Search
GET /users?q=alice
GET /posts?q=javascript&in=title,body

# Include relations
GET /posts?include=author,tags

API Security & Best Practices

Authentication Patterns

# JWT — stateless
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# API Key — simple, server-to-server
Authorization: ApiKey sk_live_abc123
X-API-Key: sk_live_abc123

# OAuth 2.0 flows
# Authorization Code + PKCE — browser SPAs, mobile apps
# Client Credentials — machine-to-machine (no user)
# Device Code — TV, CLI tools

# JWT best practices
- Short access token TTL (15 min), long refresh token TTL (7d)
- Store access token in memory (not localStorage — XSS risk)
- Store refresh token in httpOnly, Secure, SameSite cookie
- Verify signature on every request
- Include jti (JWT ID) for revocation tracking
- Never store sensitive data in JWT payload (it's only base64-encoded, not encrypted)

Security Checklist

• Input validation — validate all inputs server-side; never trust the client

• SQL injection — use parameterized queries / prepared statements, never string concatenation

• Rate limiting — limit by IP and/or user; return 429 with Retry-After

• CORS — restrict allowed origins; don't use wildcard (*) for authenticated APIs

• HTTPS only — redirect HTTP to HTTPS; HSTS header

• Error messages — never expose stack traces or internal details in production

• Sensitive data — never log passwords, tokens, PII; mask in responses (SSNs, full card numbers)

• Idempotency keys — for POST mutations (payments, emails) accept an Idempotency-Key header to prevent duplicates

Idempotency Reference

# Idempotent HTTP methods — safe to retry
GET    — no side effects
HEAD   — no side effects
PUT    — replace resource (same input = same result)
DELETE — deleting already-deleted = 404 (acceptable)
PATCH  — NOT necessarily idempotent (depends on semantics)

# Non-idempotent
POST   — creates new resource each time

# Making POST idempotent with Idempotency-Key
POST /payments
Idempotency-Key: client-generated-uuid-123

# Server behavior:
# - First request: process and store result keyed by Idempotency-Key
# - Duplicate requests: return stored result (don't process again)
# - Expiry: typically 24h