00. Backend API Design — The Five-Year-Old Version¶
The roads between buildings exist. Now we design the menus, order slips, and kitchen rules that make the restaurant actually serve food.
Imagine you run a restaurant. People walk in, sit down, and want food. You need a system.
First, you hand them a menu. The menu lists everything the restaurant offers. Each item has a name, a description, and a price. The customer doesn't need to know how the kitchen works. They just read the menu and pick.
The waiter writes the order on an order slip. The order slip has exactly what the customer wants — item, quantity, special requests. No ambiguity. The kitchen doesn't guess. If the order slip says "burger, no onions, medium rare," that is what gets cooked.
The waiter carries the order slip to the kitchen window — the single opening between the dining room and the kitchen. Everything passes through this window. The kitchen never talks to customers directly. The kitchen window is the boundary.
When the food is ready, the kitchen puts a receipt on the plate. The receipt confirms what was made, how long it took, and any substitutions. The waiter carries it back.
The whole system works because of wait staff — the people who translate between customers and kitchen. They validate orders. They handle complaints. They pace the flow so the kitchen doesn't get overwhelmed.
Backend API design is building this restaurant. The menu is your API documentation. The order slip is the request. The kitchen window is the API gateway. The receipt is the response. The wait staff are your middleware — authentication, validation, rate limiting, error handling.
A great restaurant has clear menus, precise order slips, a well-managed kitchen window, honest receipts, and skilled wait staff. A bad one has menus that lie, orders that get lost, a kitchen that ignores the window, and receipts that don't match what was delivered. Same with APIs.
The placeholders you will see called back¶
| Placeholder | Meaning |
|---|---|
| menu | API documentation — what endpoints exist and what they accept/return |
| order slip | the request — method, path, headers, body, parameters |
| kitchen window | the API gateway — single entry point between client and backend |
| receipt | the response — status code, headers, body, error details |
| wait staff | middleware — auth, validation, rate limiting, logging, error handling |
Top resources¶
- RESTful Web APIs by Leonard Richardson — the definitive guide to REST design principles and hypermedia
- gRPC Up and Running by Kasun Indrasiri — practical guide to building gRPC services with protobuf
- API Design Patterns by JJ Geewax — Google engineer's collection of patterns for consistent, scalable APIs
- Stripe API Reference — gold standard API documentation; study the patterns, not just the endpoints
- Postman Learning Center — hands-on API testing, documentation, and design workflow
What's coming¶
- 01-rest-api-design.md — resources, verbs, status codes, and the principles behind clean REST
- 02-graphql-design.md — schema-first, resolvers, N+1 problem, and when GraphQL wins over REST
- 03-grpc-and-protobuf.md — binary protocols, streaming, and service-to-service contracts
- 04-webhooks-and-callbacks.md — push-based notification, retry logic, and event delivery
- 05-auth-oauth-jwt-sessions.md — authentication vs authorization, token lifecycle, session management
- 06-api-gateway-and-routing.md — the kitchen window: routing, aggregation, and protocol translation
- 07-idempotency-and-retries.md — making APIs safe to retry without side effects
- 08-pagination-filtering-sorting.md — cursor vs offset, query parameters, and large dataset handling
- 09-versioning-and-deprecation.md — evolving APIs without breaking clients
- 10-error-handling-and-contracts.md — structured errors, problem details RFC, and client-friendly failures
- 11-rate-limiting-and-throttling.md — protecting the kitchen from too many orders at once
- 12-api-for-ai-agents.md — tool-use contracts, streaming responses, and agent-friendly API patterns
- 13-honest-admission.md — what we don't fully understand about API design
Bridge. The restaurant needs a menu first. Let's design RESTful APIs — the most common menu format on the internet. → 01-rest-api-design.md
One more thing. A great restaurant has rules for bad days too. What if the kitchen runs out of ingredients? The waiter doesn't say "error 500." The waiter says: "We're out of salmon. May I suggest the chicken instead?" That is graceful error handling.
What if 500 people walk in at once? You don't seat them all and overwhelm the kitchen. You put a line outside. You serve tables at a pace the kitchen can handle. That is rate limiting. The wait staff protect the kitchen from the dining room.