We start with what an API actually promises, then move on to choosing URLs and status codes, unifying how errors look, idempotency and retries, rate limiting, OpenAPI, GraphQL, and finally cutting versions and retiring old ones. Across 30 lessons you'll build "a yardstick for design that still works when the framework changes." Every request and response shown here comes from a real server written with nothing but the Node.js 26.9 standard library, captured with curl.
The 30 lessons are split into 6 chapters. We recommend going in order from chapter 1, but feel free to dip into whatever interests you. Note: lessons that start a server can't run in the browser, so try them with Node.js and curl on your own machine. Short snippets that only check a design decision run right in the browser.
We draw a line between your internal implementation and the promises you make to the outside world. We reread HTTP as a design tool, and finish by checking method safety and idempotency with curl on your own machine.
We decide how to shape URLs, how to choose status codes, and how to return lists. We finish by comparing paging, filtering, and sorting through the responses of a real, running server.
We give errors a single shape and build in design that assumes failure: retries, idempotency, rate limits, and deadlines. We finish by setting a deadline on an entire call.
We turn the design in your head into OpenAPI, then generate types, mocks, and tests from it. We finish by letting CI catch drift between the spec and the implementation.
We run schemas, resolvers, N+1, and error responses for real and compare them side by side with REST. You'll come away with what you need to decide which one to choose.
We decide how to cut versions and plan the steps to retire an old one. We finish by generating docs and the changelog automatically from the spec, so nothing is copied by hand.
Once you've finished all 30 lessons, head to FastAPI for Beginners to actually build the APIs you've learned to design. A membership unlocks every course.