REST API

Stateless means each HTTP request must contain all information needed to process it — no server-side session state. The server treats each request as independent. Why it matters for scalability: any server instance can handle any request because there's no affinity to a particular instance. This enables: - Horizontal scaling: spin up N replicas behind a load balancer - Resilience: a crashed instance loses no session data - Caching: responses can be cached by proxies without ambiguity Common violation: storing user session data in server memory. Fix: externalize session to Redis, or go fully stateless with JWTs that carry claims in the token. Statelessness increases per-request overhead (client resends auth, preferences every time) but the scaling and resilience benefits almost always outweigh this cost.

PUT replaces the entire resource with the provided representation. If you omit a field, it's set to null/default. It's idempotent: sending the same PUT twice produces the same state. PATCH applies a partial update — only the fields included are changed. It's not inherently idempotent (e.g., increment counter by 1 is a PATCH that isn't idempotent), though most PATCH implementations are. Choose PUT when: the client always sends the complete resource (e.g., replacing a configuration object). Choose PATCH when: you want to update specific fields without knowing or sending the full resource (e.g., updating a user's email only). Two PATCH formats: JSON Merge Patch (RFC 7396) — simple key-value overlay, null means delete field. JSON Patch (RFC 6902) — operation array (add, remove, replace, move, copy, test), more expressive.

401 Unauthorized — the request lacks valid authentication. The client is not identified. You don't know who is asking, so you can't determine what they're allowed to do. Response must include a WWW-Authenticate header indicating the auth scheme. 403 Forbidden — the client is authenticated (you know who they are) but they don't have permission to access the resource. Decision tree: - No/invalid credentials → 401 - Valid credentials, wrong role/scope → 403 - Valid credentials, resource doesn't exist → 404 (or 403 to hide existence) Security note: returning 404 instead of 403 for sensitive resources prevents information leakage — an attacker learns neither the resource exists nor that they lack permission. Use this pattern for confidential resources.

An operation is idempotent if applying it N times produces the same result as applying it once. GET, PUT, DELETE are idempotent by HTTP contract. POST is not. Why it matters: clients retry on network failures. If POST /payments isn't idempotent, a retry after a timeout creates a duplicate charge. Making POST idempotent with idempotency keys: 1. Client generates a UUID and sends it as Idempotency-Key: <uuid> header 2. Server stores {key → response} in a fast store (Redis) with a TTL (24 hours) 3. On receipt: if key seen before, return stored response immediately; if not, process and store result atomically 4. Return the same response (including status code) for duplicate requests The storage must be atomic: use Redis SET key value NX EX <ttl> to prevent races where two simultaneous requests with the same key both proceed.

Offset/Limit (?offset=40&limit=20): - Pro: random page access, simple to implement - Con: unstable (inserts/deletes shift rows between pages), slow at high offsets (DB must scan all preceding rows), inconsistent results for real-time data

Cursor-based pagination: - Server returns an opaque cursor (base64 of timestamp + last ID) - Client passes ?cursor=<token> on next request - Pro: stable, consistent, O(log n) with index, works for infinite scroll - Con: no random page jump, cursor becomes invalid if data is deleted Keyset pagination (?after_id=1234&after_created=2024-01-01T12:00:00Z): - Similar to cursor but uses readable columns; very fast with composite index - Good for time-ordered data (logs, events) My recommendation: use cursor-based for anything > 10k rows or with real-time updates. Always return has_more, total count where cheap, and next/prev links.

Cache-Control directives set cacheability: max-age=3600 (cache for 1 hour), no-store (never cache), no-cache (cache but always revalidate), private (browser only), public (shared caches ok). ETag is an opaque fingerprint of the resource (hash of content or version). Server includes it in GET responses. Client stores it. Conditional requests: - If-None-Match: <etag> — client asks "return body only if changed." Server returns 304 Not Modified (no body, saves bandwidth) or 200 with new body. - If-Match: <etag> — client says "update only if resource still matches this etag." Server returns 412 Precondition Failed if modified by someone else.

ETags for optimistic concurrency: 1. GET /resource → response has ETag: "v42" 2. Client edits, sends PUT /resource with If-Match: "v42" 3. If another writer updated it in between, server returns 412 — no lost update

HTTP status code communicates the class of error. The body provides actionable detail. RFC 7807 Problem Details is the standard: json { "type": "https://api.example.com/errors/validation", "title": "Validation Failed", "status": 422, "detail": "One or more fields failed validation.", "instance": "/orders/abc", "errors": [ {"field": "quantity", "message": "must be greater than 0"} ] } Key properties: - type: URI identifying the error type (machine-readable) - title: human-readable, stable (don't change per request) - detail: specific to this request - instance: URI of the specific occurrence (links to logs) - Extend with errors array for validation failures Never expose: stack traces, internal class names, SQL errors, server paths. Always log the correlation ID (X-Request-ID) so support can trace the request.

Content negotiation lets the client and server agree on the representation format without hardcoding it. Client signals preference via Accept header: Accept: application/json, application/xml;q=0.8, */*;q=0.5 (q values are quality factors, 0–1, default 1.0) Server responds with: - Best matching format and Content-Type: application/json - 406 Not Acceptable if no match is possible Language negotiation: Accept-Language: en-US, fr;q=0.8 Encoding: Accept-Encoding: gzip, br — server can compress response Why it matters: one endpoint serves multiple consumers (JSON for web, XML for legacy SOAP clients, CSV for analytics pipelines) without separate URLs. Also used for API versioning: Accept: application/vnd.myapi.v2+json.

CORS (Cross-Origin Resource Sharing) is a browser security mechanism. Browsers block cross-origin requests unless the server explicitly allows them. Simple requests (GET/POST with safe headers): browser sends request directly; server must return Access-Control-Allow-Origin header. Preflighted requests (non-simple methods or headers like PUT, DELETE, Authorization, custom headers): browser sends an OPTIONS request first: OPTIONS /api/orders Origin: https://app.example.com Access-Control-Request-Method: DELETE Access-Control-Request-Headers: Authorization Server responds: Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: GET, POST, PUT, DELETE Access-Control-Allow-Headers: Authorization, Content-Type Access-Control-Max-Age: 86400 ← cache preflight for 24h Browser then sends the actual request. Access-Control-Allow-Credentials: true needed if cookies/auth headers must be sent cross-origin. Cannot be combined with Allow-Origin: *.

Breaking changes require a version bump. Process: 1. Release v2 alongside v1 — never replace, always add 2. Announce deprecation on v1: add Deprecation: true and Sunset: Sat, 31 Dec 2025 00:00:00 GMT headers (RFC 8594) to v1 responses 3. Communicate migration guide — exact diff of what changed, code examples 4. Monitor v1 traffic — identify active callers using API key / request logs 5. Reach out to high-volume callers before sunset 6. Return 410 Gone after sunset date — never 404 (clients need to know the resource existed and was intentionally removed)

What counts as breaking: removing fields, changing field types, renaming fields, making optional params required, changing auth scheme, changing status codes. Not breaking: adding new optional fields to responses, adding new optional request params, adding new endpoints, loosening validation.

Core mechanism: idempotency keys + saga pattern Request flow: 1. Client generates Idempotency-Key: uuid-v4 (per payment attempt, not per session) 2. Server atomically: INSERT INTO idempotency_keys (key, status='PROCESSING') ON CONFLICT DO NOTHING — if conflict, another request with same key is in-flight or done 3. Execute payment: call payment processor, write to payments table 4. Update idempotency record: {key, status='DONE', response_body, response_status} 5. Return response; subsequent retries get stored response Handling partial failures: - Payment processor times out before confirmation: store status='UNCERTAIN' - Reconciliation job polls processor for final state and updates - Client retrying gets 202 Accepted with a status check URL until resolved Audit trail: - Append-only payment_events table: every state transition (CREATED, AUTHORIZED, CAPTURED, REFUNDED, FAILED) - Include actor, timestamp, idempotency_key, processor_response on each event - Never update; read by replaying events or projecting to payments table Race condition prevention: - Redis SET key 'PROCESSING' NX EX 30 as distributed lock before DB write - Expires after 30s so a crashed server doesn't lock forever

Challenge: a single server can rate-limit locally cheaply, but with N instances behind a load balancer, local counters are siloed — each instance allows full quota. Centralized counter (Redis): - Sliding window with Redis sorted sets or atomic INCR + EXPIRE - Key: ratelimit:{api_key}:{window_start} → count - Fast (sub-ms), consistent, but Redis is now a bottleneck and single point of failure - Mitigation: Redis Cluster, read replicas for quota checks Token bucket in Redis (atomic Lua script): lua -- Atomically check and decrement token bucket local tokens = tonumber(redis.call('GET', key)) or capacity if tokens > 0 then redis.call('SET', key, tokens-1, 'EX', window) return 1 else return 0 end Approximate local + sync: - Each instance tracks locally; periodically syncs with Redis - Trades perfect accuracy for resilience; over-allows briefly during sync interval - Acceptable for most APIs; unacceptable for billing/quota-critical limits Response headers (always include): X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 743 X-RateLimit-Reset: 1704067200 Retry-After: 57 Limit dimensions: per API key, per user, per IP, per endpoint, per tier (free/pro/enterprise). Implement as a middleware/filter at the API gateway level, not per service.

Strategy: expand-contract pattern (parallel run) Phase 1 — Expand (backward-compatible): - Add new optional fields to responses (old clients ignore unknown fields if they're well-behaved JSON consumers — Postel's Law) - Accept new optional request fields with defaults that match old behavior - New endpoints can coexist with old ones Phase 2 — Migrate (dual write): - Internal logic writes to both old and new data models - New response includes both old fields (for compatibility) and new fields - Monitor which callers are using old vs new fields via analytics Phase 3 — Contract (sunset old): - Add Deprecation + Sunset headers to deprecated fields/endpoints - Remove old fields after sunset date; return 410 for removed endpoints Contract testing (Pact): - Consumer-driven: consumers publish their expectations (pacts) - Provider CI runs against pact broker; build fails if provider breaks a pact - Catches breaking changes before they reach production Field-level deprecation in OpenAPI: yaml userId: type: integer deprecated: true description: "Use userUuid instead. Removed after 2026-06-01."

Defense in layers: Transport: TLS 1.2+ everywhere. HSTS header. Certificate pinning for mobile clients that control the client binary. Authentication: OAuth2 + JWT for user-facing, API keys (hashed, stored in DB — never plain text) for machine-to-machine. Rotate keys without downtime using key IDs in headers. Authorization: - Scopes on tokens (read:orders, write:payments) - Resource-level: user can only access their own resources — always filter by authenticated identity, not a passed-in user_id param (IDOR prevention) - Rate limiting per API key + per IP Input validation: - Validate all inputs against strict schema (size limits, type, format, regex) - Reject unknown fields or strip them — prevents mass assignment - Limit JSON body size (e.g., 1MB max) to prevent large payload DoS Output filtering: - Never expose internal IDs, stack traces, DB column names in errors - Use opaque IDs (UUIDs or encoded IDs) — sequential IDs enable enumeration attacks Audit logging: - Log every mutating request with auth principal, timestamp, resource, diff - Store separately from application logs — immutable, tamper-evident API gateway features: TLS termination, auth, rate limiting, IP allowlisting, request/response logging — centralise here rather than per-service.

The core tension: internal APIs optimize for developer experience and velocity; external APIs optimize for stability, discoverability, and trust. Dual-layer architecture: - Internal APIs (BFFs and service-to-service): gRPC for performance-critical paths, REST for simpler CRUD. Versioning via Protobuf evolution rules. Deployed continuously. Contracts enforced by Pact/schema registries. - External APIs (developer platform): REST with OpenAPI spec as the contract. Semantic versioning with long deprecation windows (6–12 months). API key management, usage analytics, developer portal (docs, sandbox, SDKs).

API Gateway as the seam: - External requests hit the gateway first: auth, rate limiting, request translation - Gateway routes to internal services; internal callers bypass (or use internal gateway) - This decouples external API stability from internal service topology Design governance: - API design review board: new external APIs reviewed against style guide before release - OpenAPI-first: spec written before implementation; code generated from spec - Breaking change policy: documented, enforced, with automated Pact checks in CI Developer experience investment: - Interactive docs (Swagger UI / Redoc) generated from spec - SDKs in top languages auto-generated from OpenAPI spec (openapi-generator) - Sandbox environment with realistic test data - Webhook delivery with retry, delivery logs, and replay UI Metrics that matter for a platform: API adoption rate, SDK version distribution (how many still on deprecated versions), time-to-first-successful-call (DX metric), error rate per consumer, SLA breach rate.

Immediate triage (minutes): - Check error rate, latency P50/P95/P99, saturation (CPU, connections, DB pool) at each layer: CDN → API gateway → service → DB - Identify if degradation is global or per-endpoint/consumer - Pull slow query log; check connection pool exhaustion; check downstream dependency health (DB, cache, third-party APIs) - Apply rate limiting tighter if specific consumers are causing the spike Short-term stabilization (hours): - Scale horizontally if CPU/connection-bound (add instances) - Enable aggressive caching at gateway for GET endpoints that can tolerate staleness - Shed load: return 503 with Retry-After for non-critical endpoints - Circuit break unhealthy downstream dependencies Root cause categories and fixes: - N+1 queries on REST responses: add projection endpoints, or GraphQL where clients over-fetch; add read replicas; add response-level caching (Redis) - Missing indexes on filter params: profile slow queries, add targeted indexes - Hot partition: if sharding by customer ID and one customer is massive, rethink sharding key or add dedicated capacity - Thundering herd on cache miss: cache stampede — use mutex/lock-based cache population or probabilistic early expiration (XFetch algorithm)

Architectural response (weeks): - Read path: CQRS — separate read model (denormalized, cached) from write model - Write path: async where possible (202 + event); offload heavy processing to queues - Contract with consumers: add pagination where endpoints return unbounded results - SLA tiering: separate clusters for critical vs. background traffic; bulkhead pattern