skip to content

Client-Server API Contract

Designing the API a browser app consumes: REST, GraphQL or RPC chosen from the screens, payloads shaped against over-fetching, paging and error envelopes. It is the interface step every round asks.

on this pageshow

questions

6

In a retail-banking web app, how should the API's error envelope map onto the transfer form's field errors, page failures, retries and expired sessions?

level: middleimportance: must knowfreq 58%

answer

  1. one envelope, one interpreter
  2. branch on status and type, not text
  3. 422 pointers land under fields
  4. 401: re-authenticate, keep the draft
  5. retry the transfer with the same key

basics

~20 s

Use one envelope everywhere, problem details with a stable type and per-field errors, and map by status and type: 422 field errors inline, 401 to re-authentication keeping the draft, 503 or a lost response to a retry, the rest to a page-level state.

solid answer

~40 s

I'd have every endpoint return the same error envelope: problem details (`application/problem+json`) with a stable `type` and, for validation, an extension listing each field error with a pointer into the request. The client maps on HTTP status plus `type`, never on the `detail` text. On the transfer form, a `422` with field errors renders inline under each named field and keeps what the user typed; a business refusal such as an exceeded daily limit becomes a form-level message. A `401` means the session expired: prompt re-authentication and keep the draft. A `503` or a lost response is retryable, and the transfer is retried only with the same idempotency key. A `403`, a `404` or an unexpected `5xx` becomes a page-level state.

code

http · 12 lines
http
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://bank.example/problems/transfer-invalid",
  "title": "The transfer request is not valid.",
  "status": 422,
  "errors": [
    { "pointer": "#/amount", "detail": "must be greater than zero" },
    { "pointer": "#/destinationAccount", "detail": "is not a valid account number" }
  ]
}

go deeper

for a junior

Recall that a field error belongs under its field and that the form keeps what the user typed.

for a middle

Explain the mapping: status plus a stable type decides inline, form-level, retry, re-authenticate or page state, and why detail text is never parsed.

for a senior

Show the transfer's retry path: a lost response is not a failure, and only the same idempotency key makes a retry safe when money moves.

for a principal

Set the rule that every service speaks one envelope and the client owns the copy, and weigh it against teams' freedom to shape their own errors.

## One envelope, one interpreter If every endpoint invents its own error shape, the client needs a special case per endpoint, and the screens drift apart in how they fail. One **error envelope** for the whole API lets the client write one interpreter that turns any failure into a UI state. A ready-made envelope is **problem details** (RFC 9457, which obsoletes RFC 7807): a JSON object served as `application/problem+json` with the members `type` (a URI identifying the problem type), `title` (a short human summary), `status`, `detail` (a human explanation of this occurrence) and `instance` (a URI for this occurrence). Problem types may add **extension members**; the RFC's own example adds an `errors` list in which each entry has a `detail` and a JSON `pointer` into the request. Two rules from the RFC matter to the client: - `type` is the problem's primary identifier, so the client branches on it; - consumers should not parse `detail`, which is prose for people and may be reworded or localised. What the body should and should not contain, and how a request id reaches support, belong to the error body's own design, a neighbouring subject. This question is about what the screen does with it. ## The mapping, case by case | Situation in the banking app | HTTP status | What the client reads | UI state | |---|---|---|---| | Amount or account number invalid | `422 Unprocessable Content` | `errors[]` pointers | Message under each named field, input kept | | Business refusal (daily limit reached) | one status, as the API defines it | stable `type` | Form-level message with next step | | Payee changed since the form loaded | `409` or `412` | `type` | Reload the payee, ask to re-confirm | | Session expired | `401` | status | Re-authenticate, then return to the draft | | Not allowed (account not owned) | `403` | status | Page-level "no access", no retry | | Unknown account in the URL | `404` | status | Page-level not found | | Temporary outage | `503`, perhaps with `Retry-After` | status | Retry affordance | | Unexpected server fault | other `5xx` | `instance` for support | Page or section failure with a reference | ## The transfer form: field and form errors 1. Validate in the browser first for speed (required fields, number format), knowing the server stays the authority. 2. On a `422`, walk the `errors` list and attach each message to the field its pointer names; move focus to the first invalid field. 3. Keep everything the user typed. Clearing a payment form after a validation error is a classic defect. 4. Show a refusal that is not about one field, such as a daily limit, as a form-level message, ideally with the remaining allowance carried in an extension member. ## Session expiry is not an error page A `401` on submit means the session ended, not that the transfer failed for a business reason. The screen should prompt re-authentication without losing the draft and bring the user back to the form. Where the draft is kept while that happens is a state-placement decision; the contract's job is to make `401` distinguishable from every other failure. After re-authentication, ask the user to confirm again rather than resubmitting a money transfer silently. ## Retryable versus final - **Retryable**: a network failure, a timeout, a `503`. Reads can retry automatically with growing gaps; the transfer shows a retry action. - **Final**: most `4xx` responses, because the same request gets the same answer. - **Unknown**: a request that timed out may have been applied. The transfer is retried only with the **same idempotency key**, so the server can return the transfer it already created instead of making a second one. ## The copy belongs to the client The client maps each known `type` to its own localised message, so tone and language match the rest of the UI and a refusal can carry a useful next step. The server's `title` and `detail` remain the fallback for types the client does not yet know. A simple order of precedence keeps the interpreter small: - a known `type`: the client's own message, in the place the table above names; - an unknown `type` with a `4xx` status: the server's `title` as a form-level message, input kept; - an unknown `5xx`: a page or section failure that shows the `instance` reference for support; - no response at all: the retryable state, never a claim that nothing happened.

  • The transfer request times out and no response ever arrives. What does the screen show?
    Not 'failed': the server may have applied it. The screen shows a pending state and retries with the same idempotency key, or asks the server for the transfer recorded under that key. Either way the server answers with the one transfer it created, and the screen then shows success or the real error.
  • Why should the client hold its own message for each error type instead of displaying the server's title?
    The client owns tone, layout and language: it can phrase a daily-limit refusal with the remaining allowance and a link to raise the limit, translated with the rest of the UI. The server's `title` and `detail` stay as the fallback for types the client does not yet recognise.

  • Parsing the human-readable detail text to decide which field failed
  • Clearing the transfer form after a validation error
  • Treating an expired session as a generic something-went-wrong page
  • Retrying a timed-out transfer as a fresh POST with a new idempotency key
  • Letting each endpoint invent its own error shape for the client to special-case
open as a page

In a frontend design round for a retail-banking web app, how would you choose REST, GraphQL or RPC for its overview, transactions and transfer screens?

level: middleimportance: must knowfreq 62%

basics

~20 s

Argue it from the screens: the transactions list is a filtered, paged resource (REST), the transfer is a command (an action endpoint), and the overview's three-source fan-in decides whether GraphQL or one screen-shaped endpoint earns its cost.

open as a page

For a retail-banking web app's transactions list and detail panel, how would you shape the payloads and page envelope against over- and under-fetching?

level: middleimportance: should knowfreq 54%

basics

~20 s

Give list rows a summary representation that already carries the labels they display, fetch the detail when a row opens, and return a page envelope of cursor and has-more, adding a total count only if the screen shows it.

open as a page

For a retail-banking web app whose overview combines balances, cards and offers from three back-end services, should the frontend team build a BFF, and what would it own?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Yes for this overview: three services with their own auth and error shapes, fanned in over phone networks. A frontend-owned BFF composes one screen-shaped payload and one error envelope; business rules stay in the services. Skip it if the API already serves that endpoint.

open as a page

In a retail-banking web app, the offers service behind the accounts overview is down; what should the overview's API response carry, and what should the screen render?

level: seniorimportance: should knowfreq 43%

basics

~20 s

Return the overview with balances and cards, and mark the offers section unavailable and retryable, rather than failing the whole response or sending an empty list. The screen renders what arrived and degrades the offers slot; a balances failure justifies a page-level error.

open as a page

As lead of a retail-banking web app whose SPA and API ship from two teams' separate pipelines, who owns a contract change, and how is it ordered and rolled back?

level: principalimportance: should knowfreq 34%

basics

~20 s

The API ships first; the SPA follows, using new fields behind a flag turned on once the API is live; removals and new requirements wait until no live or rollback-target SPA build needs the old shape. Rollback runs in reverse: SPA first.

open as a page