system-design

Part 6 — API Design

The contracts through which every service, client, and partner talks to your system. The one part you can never take back once someone integrates against it.

Time for this part: Week 9 on the Standard track (alongside architecture). It’s short but disproportionately tested — API design questions appear in almost every interview, from junior CRUD rounds to senior distributed-systems designs.

The unifying idea: an API is a promise to people whose code you can’t fix. Every principle here follows from that.

Chapters

Foundations

#	Chapter	Time	The problem it solves
1	API Design Principles	18 min	Consistency, consumer-shaping, and evolvability
2	REST Done Properly	20 min	What REST actually means, and statelessness

Choosing a style

#	Chapter	Time	The problem it solves
3	GraphQL	22 min	Client-specified data — and the N+1 it creates
4	gRPC and RPC	20 min	Fast, typed, internal service-to-service

The details that scale

#	Chapter	Time	The problem it solves
5	Pagination, Filtering, Sorting	18 min	Never return an unbounded list — and why offset breaks
6	Versioning & Backward Compatibility	18 min	Evolving without breaking frozen clients
7	Webhooks and Callbacks	18 min	The server calling the client, reliably
8	Error Handling Contracts	16 min	How you fail is part of the contract

The five things to remember

Consistency is the top quality of an API. A developer should guess the next endpoint from the last. Same naming, dates, errors, and pagination everywhere.
Statelessness is what makes REST scale. Each request carries its own context; any server serves any request.
Clients must ignore unknown fields. It’s the foundation of forward compatibility — and the thing that lets you add fields without a version bump.
REST at the edge, gRPC internally, GraphQL for flexible clients, webhooks for event notifications. Different tools for different consumers.
How you fail is a contract. Correct status codes (4xx don’t retry, 5xx do), a consistent error body with stable machine codes, a request ID on everything, and no leaked internals.

The choose-your-style cheat sheet

Public API, CRUD, cacheable, browser        → REST/JSON
Internal service-to-service, high volume     → gRPC
Many clients, diverse data shapes            → GraphQL
Notify a third party of an event             → Webhooks
Real-time bidirectional                      → WebSockets (see Part 2)

Before moving on

You should be able to answer these without notes:

Explain why the API shouldn’t expose your database schema.
Explain PUT vs PATCH, and why statelessness makes REST scale.
Explain the N+1 resolver problem in GraphQL and how DataLoader fixes it.
Explain why gRPC is fast, and why it isn’t browser-native.
Explain why offset pagination breaks at depth, and design cursor pagination with a tiebreaker.
Classify API changes as breaking or non-breaking — including the enum-value subtlety.
Design a webhook handler: ACK-fast, dedupe, verify signature, handle out-of-order.
Design an error contract with correct status codes, stable codes, and a request ID.

Next: Part 7 — Security — protecting the systems and APIs you’ve just designed.

This site is open source. Improve this page.