Course Review

# WHAT: API project decision checklist — ask these before and during every build

# ── DESIGN ─────────────────────────────────────────────────────────────────
[ ] What is the resource model? Name every noun the API exposes.
[ ] What HTTP method maps to each operation?
    GET to read, POST to create, PATCH to partial update, PUT to replace, DELETE to remove.
[ ] What status code does each operation return on success and on each error?
[ ] Are list endpoints paginated? Cursor for live data, offset for static snapshots.
[ ] Are update endpoints PATCH (partial) or PUT (full replacement)?
[ ] What fields belong in the response? Remove anything the client does not need.

# ── SECURITY ───────────────────────────────────────────────────────────────
[ ] Which endpoints require authentication?
[ ] What authentication mechanism? JWT for stateless, sessions for stateful.
[ ] What is the token lifetime? Short-lived access + long-lived refresh is the standard.
[ ] What authorization is needed? Who can do what — role check or ownership check?
[ ] Is rate limiting needed? Per user, per IP, or per API key?
[ ] Are there inbound webhooks? Verify HMAC signatures before processing.
[ ] Are there third-party integrations? OAuth 2.0 — never ask for passwords.
[ ] Where are secrets stored? Environment variables. Never in source control.

# ── RELIABILITY ────────────────────────────────────────────────────────────
[ ] What happens if a downstream service (Slack, S3, Stripe) is slow or down?
    Move to a background queue. Do not block the request path.
[ ] Can clients safely retry failed requests?
    Add idempotency keys to any endpoint where duplicate execution causes harm.
[ ] What gets cached? Hot reads that change less often than they are requested.
[ ] What is the database query pattern for each list endpoint?
    Check for N+1 queries. Use JOINs or batch loads.
[ ] Are there missing database indexes?
    Every WHERE clause column and every foreign key needs an index.

# ── ERRORS ─────────────────────────────────────────────────────────────────
[ ] Is there a shared error builder used by every controller?
[ ] Does every error response include: type, message, code, param, request_id?
[ ] Does the global error handler strip stack traces from production responses?
[ ] Are specific HTTP status codes used for specific errors?
    400 bad input, 401 auth, 403 forbidden, 404 not found, 409 conflict, 429 rate limit.

# ── DEPLOYMENT ─────────────────────────────────────────────────────────────
[ ] Is NODE_ENV=production set on the server?
[ ] Are environment variables in a 600-permission file, not in source control?
[ ] Is the process managed by PM2 with pm2 save and pm2 startup configured?
[ ] Is there a reverse proxy (Nginx) handling HTTPS and X-Forwarded-For?
[ ] Is there a health check endpoint and a monitor that alerts on failure?
[ ] Is there a recovery alert — not just a down alert?

# WHAT: Complete concept reference — APIForge Web APIs course

# ── HTTP FUNDAMENTALS ──────────────────────────────────────────────────────
HTTP Methods (L6)
  GET    — read a resource, no side effects, safe to retry
  POST   — create a resource or trigger an action
  PUT    — replace a resource entirely
  PATCH  — update specific fields of a resource
  DELETE — remove a resource

Status Codes (L7) — most important ones
  200 OK             — read, update, delete success
  201 Created        — resource successfully created
  202 Accepted       — request received, processing async
  301 Moved          — permanent redirect
  400 Bad Request    — client sent invalid input
  401 Unauthorized   — authentication required or failed
  403 Forbidden      — authenticated but not permitted
  404 Not Found      — resource does not exist
  409 Conflict       — duplicate or state conflict
  413 Too Large      — payload exceeds size limit
  415 Unsupported    — media type not accepted
  429 Too Many       — rate limit exceeded
  500 Server Error   — unhandled server-side failure
  502 Bad Gateway    — upstream service unreachable
  503 Unavailable    — server temporarily unable to handle request

# ── REST DESIGN ────────────────────────────────────────────────────────────
REST Principles (L10)
  Stateless         — each request carries all context, no server-side session
  Resource-based    — URLs name things (nouns), methods name actions (verbs)
  Uniform interface — consistent structure across all endpoints

Cursor Pagination (L14, L34)
  Use when:  data is live and changes between page requests
  How:       WHERE id < cursor ORDER BY id DESC LIMIT n+1
  Signal:    has_more: true/false tells client when to stop

Versioning (L15, L34)
  URL prefix:       /api/v1/* — simple, visible, forces migration
  Header-based:     APIForge-Version: 2024-11-01 — client controls migration timing

# ── AUTHENTICATION AND SECURITY ────────────────────────────────────────────
JWT (L21, L32)
  Header.Payload.Signature — base64 encoded, not encrypted
  Verify with: jwt.verify(token, secret) — throws on invalid or expired
  Access token:  short-lived (2h), carries userId, email, role
  Refresh token: long-lived (7d), carries userId and type:"refresh" only

bcrypt (L32)
  Salt rounds 10 — each hash takes ~100ms, brute force impractical
  Compare: bcrypt.compare(plain, hash) — never compare plain text

Rate Limiting (L23, L30)
  Redis atomic incr — race-condition-safe counter
  Key format: rl:{userId}:{windowMinute}
  Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
  429 response must include Retry-After header

HMAC Webhook Signatures (L34, L35)
  Sign: HMAC-SHA256(secret, timestamp + "." + body)
  Header: APIForge-Signature: t={ts},v1={sig}
  Verify: recompute and compare — reject if timestamp older than 5 min

OAuth 2.0 (L20, L35)
  state parameter — CSRF protection on the callback
  Scopes          — minimum required permissions only
  Token storage   — encrypted at rest, never logged

# ── PERFORMANCE ────────────────────────────────────────────────────────────
N+1 Queries (L30)
  Problem: 1 query for list + N queries for each row's related data
  Fix:     JOIN query or batch load with IN clause

Compression (L30, L38)
  gzip level 6 — best ratio/speed balance for JSON payloads
  JSON compresses 85-95% — 1.4MB becomes 89KB

Idempotency Keys (L34, L37)
  Client generates per logical operation (not per retry)
  Server stores response in Redis with 24h TTL
  Replay: return stored response, add Idempotency-Replayed: true header

Pre-signed URLs (L35)
  Client requests URL from API (tiny request)
  Client uploads directly to S3 using URL (no API server involved)
  URL expires in 5 minutes — capability token, not permanent access

# ── DEPLOYMENT ─────────────────────────────────────────────────────────────
PM2 (L38)
  cluster mode  — one process per CPU core
  pm2 save      — persist process list across reboots
  pm2 startup   — register PM2 as systemd service
  pm2 reload    — zero-downtime reload (new code, same port)

Nginx (L38)
  Reverse proxy — forwards HTTPS to Node on localhost:3000
  X-Forwarded-For — passes real client IP to Node
  HSTS — forces HTTPS at browser level for 1 year

Environment Security (L38)
  chmod 600 .env — owner read/write only
  Never commit .env — only .env.example goes to git
  Boot validation — crash with clear error if required var missing