Correctness · money · durable delivery · limits

API contracts that survive failure.

Design, defend, and debug APIs when clients retry, webhooks duplicate, limits trip, and money must not double-count. Mechanism + math + debug — not “use REST.” Full course below; start on the CMD spine if you want the production path.

B · MoneyIdempotency in practice — double-click safe charges. C · LimitsRate limiting algorithms + distributed Redis story. A · DeliveryWebhooks: HMAC, at-least-once, retries.

CMD start path spine first

Same niche as the sister systems guide: correctness · money · durability at the API plane. Full map: docs/CMD-BRIDGE.md. Calibration plan: docs/REVIEW-5-API-DESIGN.md.

SLIs / SLOs

Error budgets before features.

Idempotency

Retries without double effects.

Webhooks

At-least-once outbound contracts.

Webhook system

Durable delivery pipeline.

Idempotency practice

Pay button, lost response, keys.

Payments at scale

Ledger, state machine, limits.

Stripe case study

Money API design in the wild.

Saga checkout

Compensate multi-step flows.

Rate limiting

Five algorithms + distributed.

API gateway

Front door policies & failure.

Circuit breaker

Fail fast under dependency death.

Consistency & CAP

What the API can honestly promise.

↻ Review deckSpaced-repetition drills on every quiz you miss. ⏱ Mock interviewTimed design prompts + model answers to self-score. ⌕ SearchJump to any concept across 123 lessons.

0 / 123 lessons complete

Part 1 — Foundations10/10

How the machinery under every API works. Master this and the rest is application.

What an API really is

Contracts, not code — the promise between two programs.

What makes an API good

Qualities of a great contract; design-first vs code-first; the lifecycle.

Layers & the narrow waist

TCP/IP & OSI layers and why everything funnels through IP.

Latency vs throughput

The two numbers, the four delays, and percentiles.

Network sockets

The pipe every API rides on: ports, TCP handshake, keep-alive.

How the Web works

URLs, DNS, and the full lifecycle of a request.

HTTP & how it evolved

Methods, status codes, headers; 1.0 → HTTP/3 over QUIC.

Remote procedure calls

Making a network call feel local — and where the illusion leaks.

WebSockets & real-time

Two-way channels: polling vs SSE vs WebSockets.

SLIs, SLOs & SLAs

Measuring reliability and spending an error budget.

Part 2 — Data & Formats3/3

How API data is represented on the wire and why format choice matters.

df-01

Data representation & efficiency

Serialization, schemas, and compression on the wire.

df-02

Textual formats: JSON, XML

Human-readable payloads and their trade-offs.

df-03

Binary formats: Protobuf, Avro

Compact, schema-driven encoding for speed and size.

Part 3 — Architectural Styles7/7

REST, GraphQL, gRPC — what each is and when to reach for it.

as-01

Web API styles overview

Request-response, query, and RPC families compared.

as-02

REST architecture style

Resources, uniform interface, statelessness, HATEOAS.

as-03

RESTful APIs in practice

Richardson maturity, naming, status codes, pagination.

as-04

GraphQL: a query language

One endpoint, client-shaped responses, N+1 traps.

as-05

gRPC framework

Protobuf + HTTP/2 streaming for internal services.

as-06

Comparing the styles

A decision guide: pick the right style per use case.

as-07

Client-adapting APIs

Content negotiation, sparse fields, and the BFF pattern.

Part 4 — Resource Design Patterns8/8

Build-along resource modelling — standard & custom methods, field masks, long-running ops, batch, soft delete — ending in a complete mock API you can stand up.

rdp-01

Resource-oriented design & naming

Model the domain as resources, collections, and a clean hierarchy.

rdp-02

Standard methods (CRUD)

List, Get, Create, Update, Delete — the canonical contract.

rdp-03

Custom methods (:verb)

Actions that aren't CRUD, done the REST way.

rdp-04

Partial updates & field masks

PATCH with update_mask — change only what you mean to.

rdp-05

Long-running operations

Async operation resources you poll to completion.

rdp-06

Batch operations

batchGet/Create/Update/Delete — kill the N+1 round trips.

rdp-07

Soft delete & validation

Recycle-bin deletes, undelete, expunge, and dry-run.

rdp-08

Capstone: build a mock API

Assemble every pattern into a complete, buildable mock.

Part 5 — Security12/12

Protecting APIs end to end: transport, identity, and input.

sec-01

API security threats

The threat model and the OWASP API risks.

sec-02

Transport Layer Security (TLS)

Encryption, certificates, and the TLS handshake.

sec-03

Securing APIs with input validation

Injection, allow-lists, and never trusting the client.

sec-04

CORS, explained

The same-origin policy and how CORS safely relaxes it.

sec-05

Authentication vs authorization

Who you are vs what you may do.

sec-06

OAuth 2.0

Delegated access, tokens, and the common flows.

sec-07

OpenID Connect & SAML

Federated identity and single sign-on.

sec-08

API keys, JWTs & a checklist

Bearer tokens, JWT pitfalls, and a hardening checklist.

sec-09

Cookies, sessions & CSRF

Web state, session vs token auth, and CSRF defenses.

sec-10

Threat modeling (STRIDE)

Think like an attacker: trust boundaries and the six threat classes.

sec-11

OWASP API Security Top 10

Deep dive: Server-Side Request Forgery (SSRF), Mass Assignment, and Sensitive Flow abuse.

sec-12

Advanced OWASP API Risks

Deep dive: inventory audits, stack trace leaks, and unsafe consumption.

Part 6 — Reliability & Scale19/19

The patterns that keep APIs correct and fast under load.

rel-01

API versioning

Evolving without breaking callers.

rel-02

Idempotency

Making retries safe; idempotency keys in practice.

rel-03

Rate limiting algorithms

Token/leaky bucket, fixed & sliding windows — with code.

rel-04

API gateway deep dive

The front door: routing, auth, limiting, aggregation.

rel-05

Retries & backoff

Exponential backoff, jitter, and retry storms.

rel-06

Circuit breaker pattern

Failing fast to protect a struggling dependency.

rel-07

Caching at every layer

Client, CDN, gateway, app, and DB caches.

rel-08

Load balancing

Spreading traffic; L4 vs L7; health checks.

rel-09

Monitoring & observability

Metrics, logs, traces, and the four golden signals.

rel-10

Event-driven & pub/sub

Queues, topics, and decoupling with messages.

rel-11

Evolving APIs safely

Additive change, tolerant reader, expand-and-contract.

rel-12

Designing webhooks

Payloads, HMAC signing, retries, replay, idempotent consumers.

rel-13

Capacity estimation

Back-of-the-envelope sizing: QPS, storage, servers for N users.

rel-14

Scaling 1 → 1M users

Vertical vs horizontal, statelessness, the architecture progression.

rel-15

Scaling the database

Read replicas, sharding, hot keys, denormalization, CQRS.

rel-16

Consistency & CAP

Strong vs eventual, CAP/PACELC, quorum, stale reads.

rel-17

High availability

No SPOF, multi-AZ/region, active-active, failover.

rel-18

Resilience & disaster recovery

Graceful degradation, bulkheads, load shedding, RTO/RPO, chaos.

rel-19

Chaos & progressive delivery

Canary deployments, traffic shifting math, feature flagging, connection draining, and proactive fault injection.

Part 7 — Performance5/5

Estimating and shrinking response time.

perf-01

Estimating response time

A repeatable method to estimate an API's response time.

perf-02

Latency budgets

Splitting a target across hops and components.

perf-03

Speeding up page loads

Critical path, payload size, and round trips.

perf-04

Data fetching & pagination

Cursor vs offset, batching, prefetch, debouncing.

perf-05

Server vs client rendering

SSR, CSR, SSG and what each means for your API.

Part 8 — Production at Scale10/10

Interactive simulators + evidence-based scaling walkthroughs — drag the load toward 100M and watch the behaviour. Figures are first-principles models, cited and labeled.

sim-01

Part 9 — Platform & API Product Engineering9/9

Your API as a product others build on: nested quotas, webhook delivery, error models, multi-tenancy, dev-platform keys, platform auth, metering — ending in a full developer-platform design.

plat-01

Part 10 — Debugging & Real-World6/6

Diagnosing real API failures — the skills interviews and on-call both test.

dbg-01

Part 11 — Design Case Studies22/22

The repeating interview pattern: requirements → decisions → API model → evaluation.

cs-00

Part 12 — Failure Case Studies4/4

What real outages teach about API design.

fail-01

Part 13 — Interview Prep7/7

Drill, self-test, and a repeatable method to ace the interview.

prep-01

Part 14 — Wrap-up1/1

wrap-01

Where to go next

Consolidate, keep practising, ship something.