Checkpoint: APIs

Introduction

Ten lessons ago, an API was "some URLs that return JSON." Look at what it is now: a contract between strangers that a newcomer can guess (API Design & REST), that never returns everything at once (Pagination), that survives a double-click on Pay (Idempotency), in bytes you chose deliberately (Data Formats), that changes without breaking a single old client (Schema Evolution), that lets the client shape the response (GraphQL) or streams typed calls between your own services (gRPC & Streaming), behind one governed front door (API Gateways), that knows who's calling (AuthN vs AuthZ) — and that can even borrow permission from another company without ever seeing a password (OAuth2 & SSO).

That's not a list of features. It's a language — the complete grammar your servers use to speak to the world, and every piece of it was a decision someone made on purpose.

So this checkpoint hands you the decisions. Below is PrintPress, a photo-print marketplace that needs its entire API surface designed: a mobile app, partner integrations, internal services, payments, and a "import from Google Photos" button. Ten calls to make — one per lesson. No recall questions, no definitions. Just the thing you'd actually do at a whiteboard, with the architecture assembling itself as you commit.

A single map of everything the APIs section taught, drawn as one product's complete API surface. On the left, the two kinds of callers: the mobile app and a partner integration. Their requests flow into an API gateway drawn as a cutaway with its chambers in the production order — TLS termination, then the cheap IP-level rate limit, then authentication, then the per-user rate limit that needs identity to exist, then routing. Past the gateway sits the public contract strip: a REST request line reading POST /orders returning 201 with a Location header, a cursor-paginated feed where the bookmark is a value rather than a position, and an Idempotency-Key chip guarding the payment call so a retry can never double-charge. Deeper in, the internal zone: order, pricing, and rendering services talking gRPC over one persistent connection, protobuf contracts shared as a .proto file, and a server-streaming lane carrying live print-job progress dots. On the right, the identity column: a signed JWT drawn as a seal that any service verifies without a database lookup, its short life anchored by a refresh token, and below it the OAuth dance in miniature — the app redirecting to Google, consent, a code coming back on the visible channel and tokens on the private one, so the app imports your photos without ever seeing your password. Ten small numbered chips pin each of the section's ten lessons onto the exact spot in the anatomy where that decision lives. The takeaway underneath: ten decisions, one language — the complete grammar your servers use to speak to the world, and the checkpoint asks you to speak it.

See It: Ship the API

Read each brief, make the call, and watch the canvas — every decision you commit draws its piece of PrintPress and sets requests moving through it. Two things to notice while you work. First, the contrasts inside one product: partners get JSON and REST, but your own services speak protobuf over gRPC, and your own mobile app gets a GraphQL front door — the same company answers the same question differently because the context flips it. Second, wrong answers don't just score a zero — they play out. Pick offset pagination and watch the duplicate rows flash as writes land. Skip the idempotency key and watch the retry double-charge. Put the user rate-limit before authentication and watch an anonymous flood sail through, uncounted.

Grade when you're done. Every slot explains itself and names the lesson to go back to — and if you land all ten, you've earned the title.

Ship the API — design PrintPress, a photo-print marketplace, by making the ten decisions this section taught, one per lesson, and watch the architecture draw itself as you commit each one. You pick the request line a partner uses to create an order, how the order feed pages under constant writes, what makes the payment call safe to retry, which wire format strangers get versus what your own services speak, how a new field ships without breaking year-old mobile apps, what shape the mobile home screen's data takes, how internal services call each other and stream print-job progress, the order of the gateway's chambers, how the app proves who a user is on every request, and how it borrows read-only access to Google Photos without touching a password. Every commitment adds its piece to a live canvas with requests already moving through it — choose wrong and you watch the failure play out first: the double charge lands, duplicate feed rows flash, an anonymous flood sails through a mis-ordered gateway. Grade it and each slot tells you why, naming the lesson to revisit; ten out of ten makes you an API Architect. The same product forces the contrasts that matter: JSON for partners but protobuf inside, REST for strangers but a GraphQL front door for your own mobile app — context flips the answer, and the canvas shows you why.

What You Can Now Do

Walking out of this section, you can — concretely, at a whiteboard or in a design review:

Design an endpoint a stranger can guess: plural-noun resources, the right verb with its safety/idempotency contract, and the precise status code — 201 with a Location, 204 for a silent success, 400-vs-422, 401-vs-403, and never, ever a 200 wrapping an error.
Page any list safely: say why offsets lie under writes (positions move; values don't), reach for a cursor with a unique tie-breaker, and push back when someone asks for total_count on every page.
Make money-moving calls retry-safe: mint an idempotency key per intent, claim it atomically, store the outcome, replay the repeat — and explain the check-then-act race that makes "just check first" wrong.
Choose a wire format with reasons: JSON for strangers, protobuf for your own high-volume RPC, Avro where streams outlive producers — and cite the string-heavy caveat that deflates the "binary is always smaller" myth.
Change a schema without breaking anyone: add optional-with-default as the workhorse, name which reader breaks before you ship, treat renames as delete-plus-add, and version as the last resort, not the first.
Pick the client-facing shape: REST for strangers and CDN-cacheable reads, GraphQL as the BFF when many diverse clients need differently-shaped data — plus the N+1 and query-cost costs you're signing up for.
Wire the inside differently from the outside: gRPC with propagated deadlines for service-to-service, streaming where the data actually flows, and the browser-gap answer for why the edge still speaks HTTP.
Order a gateway pipeline and defend it: cheap and identity-free first, per-user limits only after authentication, and the two failure stories (silent flood, CPU-farming) for the two wrong orders.
Explain auth end-to-end: authN then authZ, sessions when you need instant revocation, short-lived JWTs plus refresh tokens when you need lookup-free scale — and why the payload being readable isn't a bug.
Integrate with anyone's account safely: run the OAuth dance, say which channel carries the code and which carries the tokens, demand PKCE, and catch the id_token-as-access-token bug in review.

Key Takeaways

An API is a promise made to people you'll never meet. Every §6 decision — verbs, cursors, keys, formats, versions — exists to keep that promise cheap to make and safe to keep.
Context flips answers. JSON and protobuf, REST and GraphQL, sessions and JWTs all won a slot in the same product. The skill isn't knowing the "best" tool — it's naming the context that picks it.
The retry is the natural enemy of money, and the write is the natural enemy of the offset. Idempotency keys and cursors are the two guards you'll reach for weekly, forever.
Order is design. The gateway pipeline, the deploy sequence for schema changes, the OAuth redirect dance — in each one, the sequence is where the security and correctness live.
Identity stacks: who are you (authN) → what may you do (authZ) → what may you do on someone else's behalf (OAuth). Three questions, three mechanisms, one column of the map.

Next, the course leaves request-and-response entirely. A feed that updates itself, a server that pushes, work that happens later, services that talk through queues — §7: Real-time & Async Communication starts with the simplest possible question: what if the client just… keeps asking?