ADR-0013: Centralized API layer & server-state discipline
Status: Accepted
Date: 2026-06-05
Scope: core (any frontend consuming a REST API)
Context
API access decays into chaos through three habits: URLs hardcoded at call sites
(unsearchable, drift-prone), React Query cache keys written as ad-hoc arrays
(invalidation misses them), and auth/error handling re-implemented per request.
Each is invisible at review time and expensive at debug time.
Decision
Three single sources of truth per app:
src/api/endpoints.ts — every endpoint as an ENDPOINTS const
(path-only builders for parameterized routes). Never hardcode a URL at a
call site.
src/api/queryKeys.ts — a query-key factory
(queryKeys.<domain>.list(params) / .detail(id) / .all). Never write a
raw key array.
src/api/axios.ts — one client instance owning cross-cutting concerns
via interceptors (bearer token injection; 401 → clear session + redirect;
app-specific response handling). Request code never deals with auth.
Server-state conventions (React Query):
Mutations use mutateAsync when the caller needs to await or catch;
on success, invalidate the relevant query keys (via the factory) so the
cache never serves stale entities. Direct setQueryData is the exception for
instant-feedback updates, not the rule.
Shared types mirror backend DTO names exactly (see the backend’s 0011-dto-design-rules) — a DTO name is a cross-repo search key. Top-level
types stay complete; slim embedded types follow <Parent><Child>Response.
Consequences
“Where is this endpoint used?” is one grep; invalidation can’t miss renamed
keys; auth changes happen in one file.
New developers (and agents) extend tables instead of inventing plumbing.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
export const queryKeys = { expenses: { all: ['expenses'] as const, list: (params: object) => ['expenses', params] as const, detail: (id: string) => ['expenses', id] as const, summary: (params: object) => ['expense-summary', params] as const, }, paymentMethods: { all: ['payment-methods'] as const, billingCycles: (id: string, params: object) => ['payment-methods', id, 'billing-cycles', params] as const, },};
Keys are declared in one file rather than inlined at each useQuery. That is what makes
invalidation safe: a mutation invalidates queryKeys.expenses.all and every list, detail
and summary underneath it refetches, because they were built from the same prefix. Keys
scattered as string literals drift, and the bug is a stale screen rather than an error.
The other half of the layer is the axios instance — one place that attaches the bearer
token and one interceptor that handles a 401 by refreshing and retrying:
/** Requests that must never be retried through the refresh path. */const NO_RETRY = [ENDPOINTS.auth.refresh, /* … */];/** Marks a request already retried once, so a second 401 ends the session. */
Both comments guard the same trap: a refresh call that itself 401s, retried through the
refresh path, is an infinite loop that reads as the app hanging.
0013-sessions-and-refresh-tokens (core backend) — with refresh tokens, the 401
interceptor refreshes and replays the request instead of clearing the session (its §7)