REST for frontends

The problem: every endpoint is a surprise

Picture a team building a small notes app. The first backend developer adds GET /getNotes?user=7, and the second adds POST /notes/delete with the id in the body. The third adds POST /updateNoteTitle, which answers 200 OK with { "success": false, "msg": "too long" } when the title is invalid.

Each endpoint works. Together they are a mess.

The frontend pays for that mess. Every call needs its own code: how to send the input, how to tell success from failure, what to do on a timeout. A generic data layer is impossible, because nothing is generic. The browser cache, the CDN, and libraries like TanStack Query cannot help either, because they rely on HTTP meaning what it says.

What goes wrong in practice

• Errors hide inside 200s. fetch only rejects on a network failure, never on a status code. If the server answers 200 with success: false, monitoring sees a healthy API while users see a broken form.
• Retries become dangerous. A phone on a train sends POST /updateNoteTitle, the connection drops, and the app has no idea whether it landed. Without rules about which calls are safe to repeat, the app either never retries (and loses work) or always retries (and duplicates it).
• Caching breaks. A delete sent as GET /deleteNote?id=3 can be prefetched by the browser or replayed by a proxy. Caches and crawlers assume GET changes nothing.
• Screens make too many calls. Endpoints shaped around database tables, not screens, force a page to make five calls in a chain before it can paint.

REST (Representational State Transfer, a style described by Roy Fielding in 2000) is the cure most web APIs reach for. In practice it means a short list of conventions: name things as resources with URLs, act on them with the standard HTTP methods, report the outcome with real status codes, and let HTTP features such as caching headers do their jobs.

Why this is a frontend topic

The API is the contract the UI is built on. A frontend engineer reads it, often helps design it, and is the first to suffer when it is wrong. In a frontend system design interview, the Interface part of the RADIO framework (Requirements, Architecture, Data model, Interface, Optimizations) is where you design it out loud: which endpoints the screen needs, what they return, how they page, and how errors come back.

This lesson walks through each part from the client's side: resources and verbs, the status codes a UI must handle, a single error shape, safe retries, query parameters for lists, caching headers, versioning, and shaping endpoints around a screen. It ends with how to present all of it in an interview.

The mental model: nouns with addresses, a few verbs

Keep one picture in your head: the API is a set of things, each with an address, and you can only do a handful of standard actions to any of them. The things are called resources. The address is the URL. The actions are the HTTP methods. What travels over the wire is a representation of the resource, usually JSON.

A library catalog is a fair comparison. Every book has a shelf number, and you can look a book up, add a new book, replace its catalog card, correct one line on the card, or remove it. The verbs are the same for every book; only the shelf number changes. Nobody invents a new verb called "borrowTheBlueBook".

Collections and items

Resources come in two shapes. A collection is a list, like /notes, and an item is one member of it, like /notes/42. Use plural nouns for collections and put the id after them. The pair gives you almost every endpoint a screen needs:

Nesting, and when to stop

When a resource only makes sense inside another, nest it once: /notes/42/comments lists the comments on note 42. Stop at one level. A URL like /users/7/notes/42/comments/9 forces the client to know three ids just to read one comment. Once a child has its own global id, give it a top-level home too: /comments/9.

Actions that are not plain edits

Some operations do not fit the five verbs neatly: publish a draft, archive a project, send an invoice. There are three honest ways to model them, and teams pick one and stay with it:

• Change a field. PATCH /posts/42 with { "status": "published" }. Best when the action really is a state change and the server validates the transition.
• Create a sub-resource. POST /invoices/9/sends creates a "send" record. It reads oddly at first, but it gives the action an id, a history, and a status you can poll.
• Use a named action. POST /posts/42:publish (Google's API guide calls these custom methods) or POST /posts/42/publish. Clear and common; just keep them rare and always on POST.

What you never do is hide a change behind GET. A GET can be prefetched by the browser, replayed by a proxy, crawled by a bot, or fired twice by a React effect in development. All of those are fine for a read and a disaster for a delete.

Representations, not database rows

The JSON you return is a view of the resource, shaped for its readers. It does not have to match a table. A note might come back with authorName copied in, createdAt as an ISO 8601 string (2026-10-19T09:30:00Z), and money as integer cents with a currency ({ "amount": 1999, "currency": "EUR" }) so JavaScript floats never round it. Ids should be strings, even when they are numbers in the database, because JavaScript loses precision past 2 to the power 53.

The verbs: safe, idempotent, and what each one promises

Each HTTP method is a promise about what happens on the server. HTTP Semantics (RFC 9110) defines two properties that matter more to a frontend than any other, because they decide what the browser, the caches, and your own code may do on their own.

• Safe: the request does not ask the server to change anything. The client can send it any number of times, ahead of time, or by accident. GET, HEAD, and OPTIONS are safe.
• Idempotent: sending the same request twice leaves the server in the same state as sending it once. All safe methods are idempotent, and so are PUT and DELETE. POST and PATCH are not, by default.

Idempotent is about the state on the server, not the response. Deleting note 42 twice may answer 204 and then 404, but either way note 42 is gone, exactly as after one delete. That is what makes the request safe to retry after a timeout.

GET and HEAD

GET reads. It has no body (servers may reject or ignore one), so all inputs go into the path and query string. Its responses are cacheable, which is the whole point: the browser cache, a CDN, and your client-side cache can all reuse them. HEAD is a GET without the body, handy to check whether a file exists or how large it is before downloading it.

POST

POST sends data for the server to process, most often to create a new item in a collection. The server picks the id and answers 201 Created with a Location: /notes/43 header and, ideally, the new note in the body so the client does not need a second request. POST is the one method you cannot blindly retry: two identical POST /orders calls make two orders. The idempotency chapter shows how to fix that.

PUT versus PATCH

PUT replaces the resource at that URL with the body you send. Any field you leave out is gone. Because the result does not depend on what was there before, PUT is idempotent. It also allows creating at a client-chosen URL, such as PUT /drafts/{clientId}, which is a neat trick for offline-first apps.

PATCH (RFC 5789) changes part of a resource, and there are two standard body formats. JSON Merge Patch (RFC 7396, Content-Type: application/merge-patch+json) sends only the changed fields, and null means "remove this field". JSON Patch (RFC 6902, application/json-patch+json) sends a list of operations such as add, remove, replace, and test. Most product APIs accept a plain partial JSON object and treat it like a merge patch.

PUT /notes/42
Content-Type: application/json

{ "title": "Groceries", "body": "milk, eggs", "pinned": false }

PATCH /notes/42
Content-Type: application/merge-patch+json

{ "title": "Groceries" }

PATCH /notes/42
Content-Type: application/json-patch+json

[{ "op": "replace", "path": "/title", "value": "Groceries" }]

A merge patch that sets a field to a value is idempotent in practice: applying { "title": "Groceries" } twice gives the same note. A patch like [{ "op": "add", "path": "/tags/-", "value": "food" }], which appends to an array, is not: run it twice and the tag appears twice. That is why HTTP does not promise PATCH is idempotent.

DELETE

DELETE removes the resource. Answer 204 No Content. If a second delete arrives (a retry), answering 404 is correct, but many APIs answer 204 again so the client sees the same outcome both times; either is fine as long as the client treats "already gone" as success. Product UIs often soft-delete, keeping the row with a deletedAt date so "Undo" can restore it.

The hidden OPTIONS request

When your app calls an API on another origin, the browser sends a CORS preflight, an OPTIONS request asking "may this origin send this method and these headers?", before any request that is not "simple". PUT, PATCH, DELETE, a Content-Type: application/json body, or an Authorization header all trigger it. Each preflight the browser has not cached adds a full round trip, 150 ms on a typical mobile link, before the real request leaves.

The server can let the browser cache the answer with Access-Control-Max-Age (browsers cap it: Chrome at 2 hours, Firefox at 24 hours). Or you can avoid the cross-origin call by serving the API from the same origin, for example through app.example.com/api.

Status codes the UI must handle, and what to show for each

A status code is the server telling the client, in three digits, what kind of outcome this is. The first digit is the class: 2xx worked, 3xx look elsewhere (or use your copy), 4xx the request was wrong, 5xx the server failed. The class alone already tells the UI the most important thing: whether trying again could help.

That one question splits the codes into groups the UI treats differently. A 4xx will fail again if sent unchanged, so the user (or the app) must change something. A 5xx, a 429, or a network error might succeed later, so a retry, automatic or manual, makes sense.

The codes worth handling, one by one

401 and 403 are not the same

The names are confusing ("Unauthorized" really means unauthenticated), so the meanings get swapped. 401 says "I don't know who you are": the fix is to sign in or refresh the token. 403 says "I know who you are, and the answer is no": signing in again changes nothing. An app that signs the user out on 403 loses their work for no reason; an app that loops refreshing tokens on 403 hammers the auth server.

Some APIs answer 404 instead of 403 for private resources, so outsiders cannot even learn that a private repository exists. GitHub does this. The UI should then phrase its not-found screen gently: "This page does not exist, or you don't have access."

400 versus 422 versus 409

These three all mean "your request was wrong" but call for different screens. 400 means the server could not even parse it: broken JSON, a missing required header. Users cannot fix that, so it is a client bug.

422 means the request was understood but the values break a rule: an email without an @, a date in the past. Users can fix it, so show the message next to the field. 409 means the values are fine but clash with the current state: the username is taken, the order was already shipped.

Plenty of APIs use 400 for all three. If yours does, the error body must say which kind it is.

Try it: one form, eight responses

Pick a response in the simulator below, a status code or a network error, and watch what a well-built "Save profile" screen does with it: what it shows, whether it keeps the user's input, and whether it retries.

One error shape for every endpoint: problem details

A status code tells the UI the kind of failure. The body must tell it the details: which field, what message, what the user can do. If every endpoint invents its own body ({ error } here, { message, code } there, { errors: [] } somewhere else), the frontend needs a parser per endpoint. Pick one shape and use it everywhere.

There is a standard one. Problem Details for HTTP APIs (RFC 9457, published in 2023, replacing RFC 7807) defines a JSON object sent with Content-Type: application/problem+json. Spring and ASP.NET Core have built-in support for it, so choosing it is rarely extra work.

The five standard members

• type: a URI that names the kind of problem, such as https://api.example.com/problems/validation. It is the stable key your code switches on. It may point to a docs page. If absent, it defaults to about:blank, meaning "nothing beyond the status code".
• title: a short human summary of that kind of problem. It should not change from one occurrence to the next, except when translated.
• status: the HTTP status code, copied into the body for convenience. It must match the real status, and it lets the client recover that status if a proxy rewrote it.
• detail: a human explanation of this particular occurrence: "Your balance is 30, but the item costs 50."
• instance: a URI for this occurrence, often a request or trace id that support can look up.

Anything else is an extension member, and this is where APIs put what the UI needs. RFC 9457's own example of several validation errors uses an errors array whose items carry a detail and a pointer, a JSON Pointer (RFC 6901) like #/email saying which field of the request is wrong. That maps directly onto a form.

What the frontend does with it

With one shape, a single request() helper turns every failure into the same error object. Components never parse bodies; they read error.fieldErrors to place messages and error.type to pick a screen.

class ApiError extends Error {
  constructor(public status: number, public problem: Problem) {
    super(problem.title ?? `HTTP ${status}`);
  }
  get fieldErrors(): Record<string, string> {
    const out: Record<string, string> = {};
    for (const e of this.problem.errors ?? []) {
      out[e.pointer.replace("#/", "")] = e.detail;
    }
    return out;
  }
}

async function request<T>(url: string, init?: RequestInit): Promise<T> {
  const res = await fetch(url, init);
  if (res.ok) return res.status === 204 ? (undefined as T) : res.json();
  const isProblem = res.headers.get("content-type")?.includes("problem+json");
  const problem: Problem = isProblem
    ? await res.json()
    : { type: "about:blank", title: res.statusText, status: res.status };
  throw new ApiError(res.status, problem);
}

Note the fallback. Not every error comes from your API: a load balancer may answer 502 with an HTML page, and a CDN may answer 503 with plain text. The helper must never assume the body is JSON just because the status is an error.

Who writes the message the user reads?

There are two schools. In the first, the server's detail is shown as is; it must then be written for end users and translated, usually by honoring the request's Accept-Language. In the second, the client maps type (plus a machine code per field, such as too_short) to its own translated copy and treats detail as a fallback. The second keeps the tone of the UI in one place and works better for apps in many languages.

Either way, never show stack traces, SQL, or internal ids in detail: they leak information to attackers and mean nothing to users.

Safe retries: idempotency keys and conditional writes

Here is the hardest moment in any client: the user taps "Pay", the request leaves, and then nothing. After 10 seconds the request times out. Did the payment go through? There are three possibilities, and the client cannot tell them apart: the request never arrived, it arrived and failed, or it arrived, succeeded, and the response was lost on the way back.

For an idempotent request, the answer does not matter: send it again. For POST /payments, retrying in the third case charges the card twice. Not retrying in the first case loses the order. Users also retry by themselves, by double-clicking or pressing the button again after a spinner that seems stuck.

The Idempotency-Key header

The fix is to make the POST idempotent by giving each logical operation a name. The client generates a unique key, for example with crypto.randomUUID(), when the user starts the action. It sends the key as Idempotency-Key: 6f1c... on the first attempt and on every retry.

Stripe made this pattern famous. An IETF working-group draft (draft-ietf-httpapi-idempotency-key-header) describes the same header, but it has not become an RFC, so treat the server behavior below as a widely copied convention that follows the draft, not a finished standard.

1. The server receives the request and looks the key up in a store such as Redis or a database table.
2. If the key is new, it saves it as "in progress", runs the operation, then saves the response next to the key.
3. If the key exists and has a saved response, it returns that response again without doing the work. Stripe replays even a saved error.
4. If the key exists but is still in progress (two retries racing), it answers 409 Conflict; the client waits and tries again.
5. If the key arrives with a different body than the first time, it rejects the request (the draft suggests 422): that is a client bug, not a retry.

Keys do not live forever. Stripe may remove them once they are at least 24 hours old, which covers every realistic retry. The important detail on the client is when the key is created: once per user intent (when the checkout screen opens, or on the first tap), never once per attempt. A key made inside the retry loop is a new key every time, which protects nothing.

async function placeOrder(cart: Cart) {
  const key = crypto.randomUUID(); // once, before the loop
  for (let attempt = 0; attempt < 4; attempt++) {
    try {
      return await request<Order>("/api/orders", {
        method: "POST",
        headers: { "Content-Type": "application/json", "Idempotency-Key": key },
        body: JSON.stringify(cart),
      });
    } catch (err) {
      // 409 here means "same key still in progress"; 500 is not retried, since a crash often repeats
      const retryable = !(err instanceof ApiError) || [409, 429, 502, 503, 504].includes(err.status);
      if (!retryable || attempt === 3) throw err;
      await sleep(2 ** attempt * 500 + Math.random() * 250);
    }
  }
}

Try the simulator: drop the response on the first attempt and compare a client that retries without a key against one that reuses its key.

The other retry problem: lost updates

Idempotency stops duplicates, but it does not stop two people from overwriting each other. Ana and Ben both open the same note, and Ana saves a new title. Ben, still looking at the old version, saves a new body with PUT, and Ana's title silently disappears. This is the lost update problem.

HTTP solves it with conditional requests. Each GET returns an ETag, a version tag such as ETag: "v7". When saving, the client sends If-Match: "v7", and if the note is still at v7, the server applies the change and returns the new tag "v8".

If someone saved in between, the server refuses with 412 Precondition Failed, and the UI can show both versions and let the user merge. A server can insist on this by answering 428 Precondition Required (RFC 6585) to writes without If-Match.

Lists: filtering, sorting, sparse fieldsets, and pagination

Most screens are lists: an inbox, search results, a product grid, an admin table. A list endpoint takes its options from the query string, so the URL alone describes the exact data you get. That matters for the frontend twice over: the same URL can be cached, and the same parameters can be mirrored in the page's own URL so a filtered view can be bookmarked and shared.

Filtering

Plain equality filters use the field name: GET /orders?status=shipped&customerId=c_19. For ranges and other operators, pick one convention and keep it: a suffix (createdAfter=2026-10-01), brackets (filter[total][gte]=100, common on JSON:API servers), or a small filter language as Google APIs do (filter=total >= 100). Repeat a key for "any of": status=shipped&status=delivered. Free-text search usually gets its own parameter, q=blue shoes.

Sorting

A widely used convention, from JSON:API, is a comma-separated list with a minus sign for descending: sort=-createdAt,name means newest first, then by name. Always add a unique field (usually id) as the last tie-breaker on the server. Without it, two rows with the same createdAt can swap places between pages, and the user sees one row twice and misses another.

Sparse fieldsets

A list of 50 products does not need each product's 4 KB description. Sparse fieldsets let the client ask for only the fields it renders: fields=id,name,price,thumbnailUrl. Google APIs call this a partial response (fields=), and JSON:API scopes it per type (fields[products]=name,price). On a phone with a slow connection, trimming a 200 KB list response to 20 KB is a visible win.

Pagination: offset or cursor

Never return an unbounded list. Cap the page size on the server (100 is a common maximum; GitHub and Stripe both use it) and let the client ask for less with limit or per_page. Then pick how the client asks for the next page.

Over-fetching, under-fetching, and designing endpoints for a screen

Resource-shaped endpoints are tidy for the server, but a screen rarely maps to exactly one resource. That mismatch fails in two opposite ways, and every REST frontend runs into both.

• Over-fetching: an endpoint returns far more than the screen needs. GET /users/7 sends 60 fields, including the bio and settings, just to draw an avatar and a name. The cost is bytes, parse time, and memory, which hurt most on low-end phones.
• Under-fetching: one endpoint returns too little, so the screen makes more calls. An order page loads the order, then the customer, then each of its 8 products: the classic N+1 pattern (one request for the list plus one per item).

Under-fetching is usually the more expensive of the two, because the calls often depend on each other. You cannot ask for the customer until the order tells you the customer id. Each dependent step costs a full round trip, and HTTP/2 multiplexing does not help, because the requests are not ready to send at the same time.

How frontends cope

Designing endpoints for a screen

The reliable method is to start from the screen, not the database. Draw the screen, mark each region, and ask three questions of every region: what data does it show, when is it needed (first paint, on scroll, on click), and how fresh must it be. The answers group regions into requests.

1. First paint gets one request. Everything visible above the fold should come from a single call (or a few parallel ones, never a chain).
2. Below the fold and on demand get their own requests. Comments, recommendations, and the second page load later and must not block the first paint.
3. Different freshness, different endpoints. A product's description can be cached for an hour; its stock count for seconds. Splitting them lets each carry its own caching headers.
4. Writes return what the screen needs next. A POST /comments that returns the created comment, with its author embedded, lets the UI insert it without a refetch.

Caching headers and versioning: an API that is fast and can change

Two HTTP features decide whether a REST API stays fast and stays usable as it grows: caching headers, which let clients and CDNs skip work, and a versioning plan, which lets the API change without breaking apps already in users' hands.

Caching headers on API responses

API responses are cached by the same rules as any HTTP response, so be explicit. Without a Cache-Control header, browsers may apply heuristic caching to a GET response that has a Last-Modified date and serve stale data with no request at all. The common choices for JSON:

Revalidation is the big win for personal data. The first GET /me/orders returns the list with ETag: "a1b2", and the next time, the browser sends If-None-Match: "a1b2" on its own. If nothing changed, the server answers 304 Not Modified with no body: a few hundred bytes instead of 40 KB, and the server can often skip rendering the JSON. Your fetch still sees a 200 with the full cached body.

Two traps. First, if a response depends on a request header, say so with Vary: an API that returns different JSON for Accept-Language must send Vary: Accept-Language, or a CDN will serve French to everyone after one French visitor. Second, never mark per-user data public: a shared cache would hand one user's orders to the next. Client libraries such as TanStack Query add their own in-memory cache on top; HTTP caching still helps on reloads, new tabs, and the CDN.

Versioning

Web apps redeploy in minutes, but old copies keep running: a tab left open since last week, a cached service worker, a mobile app that users never update. The API must keep serving the old shape for a while, so the first rule is to avoid breaking changes at all.

Adding a field, an endpoint, or an optional parameter is safe if clients ignore what they do not know (the tolerant reader rule). Renaming or removing a field, changing a type, or making an optional parameter required is breaking.

Using it in a system design interview

In a frontend system design interview, REST design shows up in the Interface step of RADIO, after you have agreed on requirements, drawn the architecture, and listed the data model's entities. The interviewer wants to see that you can turn a screen into a small, sensible set of endpoints and that you think about what happens when the network misbehaves.

What to write on the board

Spend about 5 to 8 minutes of a 45 to 60 minute interview here. Write each endpoint on one line, with its key parameters and the shape of the response, and only the endpoints this screen needs. For a news feed it might look like this:

GET    /feed?cursor=&limit=20        -> { items: Post[], nextCursor }
         Post = { id, author: { id, name, avatarUrl }, text,
                  media[], likeCount, likedByMe, createdAt }
POST   /posts   Idempotency-Key       -> 201 Post
PUT    /posts/:id/like                -> 204   (idempotent: like twice = liked)
DELETE /posts/:id/like                -> 204
GET    /posts/:id/comments?cursor=    -> { items: Comment[], nextCursor }
Errors: application/problem+json { type, title, status, detail, errors[] }

Notice the small decisions that earn points. The post embeds its author, so the feed never makes N+1 calls, and the feed uses a cursor because new posts arrive constantly. Liking is modeled as PUT and DELETE on a sub-resource rather than a POST /toggleLike, so a double tap or a retry cannot flip it back. Creating a post carries an idempotency key, so a flaky connection cannot publish it twice.

What to say, in order

1. "Let me derive the endpoints from the screen." Name the regions and which call feeds each.
2. "Lists use cursor pagination because data changes while scrolling."
3. "Writes return the created resource so the UI can update optimistically and reconcile."
4. "POSTs carry an idempotency key, so the client can retry safely."
5. "Errors share one shape, problem details, and the UI maps status classes to behavior: fix input on 4xx, retry on 429, 502, 503, 504, and network errors."
6. If time allows: caching headers, ETag for concurrent edits, and why REST over GraphQL here (or the reverse).

How deep to go by level