Summary of the first ~30 minutes ("API Design Fundamentals" and "API Protocols") of Hayk Simonyan, How to Design APIs Like a Senior Engineer (https://www.youtube.com/watch?v=7iHl71nt49o, 1 h 23 min). Later chapters (not covered here): TCP/UDP, REST in depth, GraphQL in depth, authentication, authorization, security.
Points marked (added) are not from the video.
An API is a contract between client and server: which requests can be made and what responses come back. It hides how the server works and sets clear boundaries between services, so a users service and a posts service can evolve on their own.
REST is built around resources: /v1/users/123, /users/123/posts, with HTTP verbs as the operations (GET reads, POST creates, PUT/PATCH updates, DELETE removes).
- Each request is stateless and the response structure is fixed.
- Versioning is explicit (
/v1, /v2).
- HTTP caching works through headers.
- The downside: related data can take several round trips (user, then posts, then followers is three calls).
GraphQL has one endpoint (/graphql). The client writes a query naming exactly the fields it wants, nested to any depth, and gets them in a single request.
- Reads are queries, writes are mutations, and subscriptions handle real-time updates.
- The schema usually evolves without version numbers. You add fields, or sometimes version a single field (
followersV2).
- Caching moves into the application rather than HTTP.
- Recommended for complex UIs where each screen needs different nested data.
gRPC is a high-performance RPC framework from Google: methods are defined in .proto files, messages use Protocol Buffers, and it runs over HTTP/2 with streaming in both directions. The least common of the three, and best for service-to-service traffic in microservices.
(added) Some things the video doesn't cover:
- GraphQL's costs: N+1 resolver queries (usually fixed with DataLoader), the need to limit query depth and cost, harder per-field authorization, and caching that is mostly POST-based.
- gRPC's costs: binary payloads aren't human-readable, and
.proto files need careful backward-compatible changes.
- gRPC in browsers: the video says gRPC is rare there because "browsers don't support the latest HTTP". That's not quite right. Browsers do speak HTTP/2, but they don't give JavaScript the low-level HTTP/2 control (framing, trailers) gRPC needs. So browsers need gRPC-Web, Connect or a proxy.
- Consistent: one naming and casing style and the same patterns everywhere. A GET must never have side effects.
- Simple: focus on the core use cases. "The best API is one you can use without reading the docs."
- Secure: authentication, authorization, input validation and rate limiting as the baseline.
- Performant: caching, pagination, small payloads and fewer round trips.
(added) The video's pagination is limit/offset. On large or changing data, cursor-based pagination is usually better.
- HTTP/HTTPS is the default for request/response: methods, status classes (2xx success, 3xx redirect, 4xx client error, 5xx server error) and common headers. HTTPS (HTTP plus TLS) is always the standard.
- WebSockets cover real-time and two-way traffic. Polling over HTTP wastes requests that mostly come back empty; after one handshake the server can push data.
- AMQP (message queues) covers asynchronous, guaranteed delivery: a producer puts messages on a broker's queue, and the consumer takes them when it has capacity. Typical uses are order processing and notifications.
- gRPC is HTTP/2 between servers.
Checklist for choosing a protocol: interaction pattern, performance needs, client compatibility, payload size, security needs, and developer experience (tooling and docs).
- Requirements: use cases, scope (including what's out), performance bottlenecks and security constraints.
- Approach:
- top-down: start from requirements and workflows (common in interviews)
- bottom-up: start from existing data models (common in companies)
- contract-first: define requests and responses before writing code
- Lifecycle: design → develop → deploy and monitor → maintain → deprecate and retire. Most of the work is not the coding.
| Use |
When |
| REST |
The default: public APIs, CRUD, web and mobile apps, anything that benefits from HTTP caching |
| GraphQL |
Complex or varied UIs, several client types with different data needs, cutting round trips |
| gRPC |
Internal microservices, low latency or high throughput, streaming, contracts shared across languages |
| WebSockets (a transport, not an API style) |
Chat, live feeds, anything the server must push |
| Message queue |
Work that can happen later, separating producers from consumers |
(added) Real systems often mix them: gRPC or queues between services, REST or GraphQL at the edge.