FSD Frontend System Design

Part I — The Pipes · Lesson 1.5

REST APIs

In one lineNouns as URLs, verbs as methods, state in the response — and every call stands alone.

Where you've seen itGET /2/tweets/:id on the Twitter API. Same URL, same result, cacheable by every layer in between.

  • Time16 min
  • DiagramResource tree + verb/idempotency matrix
  • Chapter1 · Networking

Diagram

diagram
RESOURCE TREE — URLs name things, not actions

  /users
  ├── /users/42                  one user
  │   ├── /users/42/posts        that user's posts
  │   └── /users/42/followers
  └── /users?role=admin&page=2   filter + paginate via query

  ✗ /getUserById?id=42     ✗ /users/42/delete     ← verbs in the URL
diagram
VERB MATRIX

  Method   Purpose        Safe  Idempotent  Cacheable  Body
  ───────────────────────────────────────────────────────────
  GET      read            ✓        ✓          ✓        no
  POST     create          ✗        ✗          ✗        yes
  PUT      replace         ✗        ✓          ✗        yes
  PATCH    partial update  ✗        ✗          ✗        yes
  DELETE   remove          ✗        ✓          ✗        no

  Safe        = changes nothing
  Idempotent  = calling it 5 times == calling it once  (retry-safe)
diagram
STATUS CODES THE CLIENT MUST BRANCH ON

  2xx  200 ok   201 created   204 no content
  3xx  304 not modified  ← ETag hit, body not re-sent
  4xx  400 bad input  401 not logged in  403 logged in, not allowed
       404 missing    409 conflict       429 rate limited → back off
  5xx  500 server bug     503 down       → retry with backoff

How it works

  1. Model resources, not procedures. /orders/9/items beats /fetchOrderItems.
  2. Pick the verb by semantics, then let infrastructure act on it — proxies cache GET, clients safely retry PUT.
  3. Return the state, plus a Location header on 201.
  4. Version at the edge — /v1/... or an Accept header — and never break a live contract.
  5. Paginate with cursors for feeds, offsets for stable tables.

Trade-offs

Use REST whenReach for something else when
Resources map cleanly to entitiesOne screen needs 6 nested resources → GraphQL
You want HTTP caching for freePayloads are huge and internal → gRPC
Many unknown third-party clientsClient needs field-level control

The classic pain: a profile screen firing /user, /user/posts, /user/followers, /user/settings — four round trips before first paint. This is exactly the gap the next lesson fills.

Interview angle

"PUT or PATCH — and why does it matter for retries?"

  • PUT replaces the whole resource and is idempotent, so a timeout can be retried safely.
  • PATCH applies a delta and generally isn't, so retries need an idempotency key.
  • On flaky mobile networks, retry safety is a design decision, not a detail.

Recap

  • URLs are nouns; methods are the verbs.
  • Idempotency decides whether a client may retry.
  • Free HTTP caching is REST's biggest advantage — and over-fetching is its biggest cost.