API Architectures
Section Descriptions
1) REST API
| File | Topics |
|---|---|
| Architecture & HTTP | REST constraints, resource design, uniform interface, method semantics (safe/idempotent), HEAD/OPTIONS, PATCH (RFC 6902/7396), status code mapping, header strategy |
| Data & Schema | OpenAPI 3.1 + JSON Schema 2020-12, strict validation, nullable vs missing, enum/range constraints, additionalProperties, mass-assignment prevention |
| Querying | Field selection, search vs filtering, sort conventions, pagination models (offset/cursor/page), metadata, mutation edge cases |
| Caching & Concurrency | Cache-Control, ETag/If-None-Match, Last-Modified, stale directives, CDN caveats, optimistic locking via If-Match, idempotency-key patterns |
| Errors, Security & Versioning | Error models (incl. RFC 9457 Problem Details), authN/authZ, rate limiting, injection defenses, CORS/HTTPS, versioning and deprecation (Sunset, Deprecation) |
| Testing & Risks | End-to-end test plan (schema/query/cache/auth/perf), concurrency and rate-limit checks, conditional write policy (428/412), risk register |
| Code Examples | Pydantic contracts, Playwright API fixtures, CRUD/query/schema/idempotency/concurrency tests |
2) GraphQL
| File | Topics |
|---|---|
| Schema & Execution | Type system, resolver design, N+1 mitigation (DataLoader), execution behavior |
| Queries & Performance | Query shaping, fragments, depth/complexity limits, caching and cost controls |
| Testing & Risks | Schema and resolver tests, subscriptions test strategy, risk scenarios |
| Code Examples | Python + Pydantic + Playwright GraphQL testing patterns |
| APQ, Safelist & Rollout | APQ vs safelisting, rollout guardrails, CI/CD governance |
3) gRPC
| File | Topics |
|---|---|
| Contract & Transport | Protobuf contracts, field numbering strategy, HTTP/2 transport specifics |
| Patterns, Codegen & Errors | Unary/streaming patterns, code generation lifecycle, status/error handling |
| Testing & Risks | Contract testing, RPC reliability tests, streaming/backpressure risks |
| Code Examples | Python + grpcio + Pydantic + gRPC-Gateway examples |
| Retry & Hedging Policy | Retry/hedging service-config baseline, idempotency and safety limits |
4) WebSocket
| File | Topics |
|---|---|
| Protocol & Communication | Upgrade handshake, frame/message contracts, ACK strategy |
| State & Scaling | Connection lifecycle, fan-out, horizontal scaling patterns |
| Testing & Risks | Ordering, reconnect/replay, fault-injection and resilience tests |
| Code Examples | Python + Pydantic + Playwright WebSocket examples |
| Reliability Pattern | Sequence + dedup + replay-window reliability model |
5) Cross-Cutting Concerns
| File | Topics |
|---|---|
| Security & Observability | Security controls, OWASP-focused checks, structured logs, metrics, traces |
| Performance & Reliability | Latency/throughput tuning, resilience patterns, capacity concerns |
| SLO, Error Budget & Incident Playbook | SLO design, error-budget policy, burn-rate alerts, incident response flow |
6) Decision Factors
| File | Topics |
|---|---|
| Comparison Guide | Protocol comparison matrix, detailed decision factors, hybrid-architecture combinations, quick selection flow |