Handbooks / System Design / Chapter 4
API Design and Gateways
7 pages · ~5 min✓ Reviewed
Builds on Scalability and Load Balancing. Next up: Caching.
API Styles: REST vs gRPC vs GraphQL
1. REST
- URLs identify resources:
/users/42 - Verbs manipulate them:
GETreads,POSTcreates PUTreplaces,PATCHchanges part,DELETEremoves- Idempotent = repeat has same effect as once
- GET, PUT, DELETE yes; POST no
- GET is also safe
- Stateless
- JSON over HTTP
- Cacheable via HTTP
2. gRPC and GraphQL
- Contract-first Protobuf over HTTP/2
- Binary, strongly typed
- Unary, server, client, bidirectional streaming
- Best for internal calls
- Single endpoint; schema: queries, mutations, subscriptions
- Fixes over- and under-fetching
- N+1: 20 users, 20 order lookups = 1+20 queries; DataLoader batches them into one
- Query names exact fields
graphql
query {
user(id: 42) {
name
orders { id }
}
}3. Choosing
| REST | gRPC | GraphQL | |
|---|---|---|---|
| Best for | Public |
REST Design: Naming, Pagination, Versioning, Idempotency
1. Resource Naming
| Rule | Do | Don't |
|---|---|---|
| Plural nouns | GET /users/42/orders | /getOrder |
| Create | POST /orders | /createOrder |
| Case | lowercase kebab-case | camelCase |
| Non-CRUD action |
API Gateway and Backend-for-Frontend
1. API Gateway
- Single entry point in front of microservices
- Routing, TLS termination, authentication
- Rate limiting, caching, logging
- Request/response transformation
- Centralises cross-cutting concerns, so no service reimplements them
- Client
- Gatewayauthenticate, rate limit, route
- Servicedomain rules
Authentication vs Authorization, OAuth 2.0 and JWT
1. Authn vs Authz
| Authn | Authz | |
|---|---|---|
| Asks | Who are you? | What may you do? |
| Fails | 401 bad or no credentials | 403 known user, denied |
2. OAuth 2.0 and Flows
Edge Rate Limiting
1. Limit at the Edge
- CDN, WAF or gateway rejects abuse before it hits the origin
- Answer 429 Too Many Requests
Retry-Aftertells the client when to return
http
HTTP/1.1 429 Too Many Requests Retry-After: 30 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0
limit headers on the rejection
2. Algorithms
- Token bucket: N tokens, refilled at a fixed rate, one spent per request
- Allows bursts up to N, holds the average rate
API Design Cheat Sheet
1. Design the API
| Style | Pick for |
|---|---|
| REST | public, cacheable |
| gRPC | internal, streaming |
| GraphQL | many clients, varying data |
- Plural nouns, no verbs, nest for ownership:
/users/42/orders - Offset: simple but drifts; cursor: stable and fast
Check yourself
A client fetches page 2 with ?limit=20&offset=20. Meanwhile 5 new rows are inserted at the top of the list. What does page 2 show?
- The last 5 rows of page 1 appear again, as duplicates
- Offsets count positions, and the insert shifted them
- Fix: cursor pagination on the last seen id
A JWT is signed with RS256 and its payload holds the claim ssn. Is the ssn safe from the client?
- No: the payload is only base64url encoded, so anyone can decode it
- The signature proves integrity, not secrecy