How API Shape Drives UI Complexity

1. 1
   Decompose the screen into requests

   Decides how many round trips before anything is renderable.

   fails by Fan-out: one request per row, so latency scales with row count (The N+1 Query Problem).

2. 2
   Issue them

   Parallel where independent, sequential where one response contains the next request's input.

   fails by A contract that forces sequencing — an id you can only learn from a previous response (Composed APIs: Aggregating Other Services).

3. 3
   Receive and parse

   Turns bytes into objects on the main thread.

   fails by Over-fetching, so a phone parses fields nothing renders (Over-Fetching and Under-Fetching).

4. 4
   Adapt to a view model

   One boundary converts the wire shape into what components consume.

   fails by Being skipped, so the wire shape leaks into every component and every future change (What a Component Owes Its Caller).

5. 5
   Key and cache

   Stores by an identity that survives refetch, so updates are updates.

   fails by Unstable ids, which turn every refresh into a remount and lose focus (Reconciliation and Keys).

6. 6
   Render, including the failures

   Shows what arrived and explains what did not.

   fails by An error model with nothing to render — no code, no field, no distinction between retryable and permanent (An Error Taxonomy Clients Can Branch On).

7. 7
   Page, refresh, mutate

   Extends the list, revalidates, writes back.

   fails by A pagination model that is not stable under concurrent writes (Pagination: Choosing How Lists End).

• A: GET /users/:id × 20 (parallel, but queued) — the fan-out: bounded by connection scheduling, not by bytes
• B: GET /orders?expand=customer — one round trip, a somewhat larger payload
• C: batch fetch (one round trip) — two sequential trips instead of one, and no per-row fan-out

B wins on round trips and pays in payload; C is the compromise available when the API cannot embed. Which is right depends on the network and the device, which is why the measurement has to happen on a realistic profile rather than the one under your desk (Latency Is a Distribution, Not a Number).

const orders = await get('/orders?limit=20')

// One request per row. Twenty round trips, plus the first.
const withCustomers = await Promise.all(
  orders.map(async (o) => ({
    ...o,
    customer: await get(`/users/${o.customerId}`),
  })),
)

// And when three of them fail?
// Promise.all rejects, and the screen shows nothing —
// including the seventeen rows that arrived fine.

// Best: the contract lets the screen ask for what it needs.
const orders = await get('/orders?limit=20&expand=customer')

// Otherwise: batch, and model partial success explicitly.
const orders = await get('/orders?limit=20')
const ids = [...new Set(orders.map((o) => o.customerId))]  // dedupe first
const { found, missing } = await post('/users:batch', { ids })

// Rows whose customer is missing still render, with an
// honest placeholder instead of an empty screen.

The fan-out is not slow because it transfers more — it transfers less. It is slow because latency is paid per request and the failures are not independent. Deduplicating the identifiers and asking once converts twenty chances to fail into one, and makes partial success something the UI can represent rather than something Promise.all erases (Eager Loading and Batching).

1{
2  "error": {
3    "code": "validation_failed",   // stable, switchable, never localised
4    "requestId": "req_9f2b41",     // what the user quotes to support
5    "retryable": false,            // could retrying ever help?
6    "message": "Some details need fixing.",   // safe to show as a fallback
7    "fields": [
8      { "path": "shipping.postcode", "code": "format_invalid" },
9      { "path": "items[2].quantity", "code": "out_of_stock", "max": 3 }
10    ]
11  }
12}
13 
14// The client can now:
15//   - put a message on the postcode input and on row 3
16//   - localise from the code, not from the message
17//   - not retry (retryable: false), and not offer a retry button
18//   - show requestId in the support link
19//
20// Compare what is possible with:  400  "Bad Request"

path is what makes an error renderable next to the input that caused it, and it is the field most often missing. Without it the client is reduced to string-matching a message — a coupling that breaks the first time someone improves the wording (The Error Model: Structure Over Apology).