Type-Safe API Clients

The plain-language idea

A common first pattern for calling an API in TypeScript looks like this: write a fetch call, then assert the response as some hand-written interface with as SomeType. It compiles, it autocompletes, it looks type-safe. But the type only describes what the API returned when the developer wrote it down — nothing re-checks that assertion against what the API actually returns today. The API can add a field, rename one, or change a type, and the hand-written interface will happily keep compiling while quietly lying about the real shape.

Two real approaches close that gap:

• Generating client types from the API's own schema. If the API publishes a machine-readable schema (an OpenAPI/Swagger-style spec is the common case), a code generator can produce matching TypeScript types directly from that spec, on demand. The types are now derived from the actual contract instead of hand-maintained, so regenerating them after an API change surfaces exactly what broke, at compile time, instead of leaving a stale as SomeType silently wrong.
• End-to-end type-safety across a shared codebase. Some approaches (broadly, tRPC-style patterns — described here as a category, not a specific current API surface to memorize) let the same codebase or a shared internal package define both the server's actual implementation and the client's call signatures together. A change to what the server returns becomes a compile error on the client immediately, because the client's types are the server's types, not a separate description of them.

See it in a real thing: an assumption that quietly goes stale

// Hand-written and asserted — nothing keeps this honest over time
type Order = { id: string; total: number };

async function getOrder(id: string): Promise<Order> {
  const res = await fetch(`/api/orders/${id}`);
  return res.json() as Order; // trusts the shape, doesn't check it
}

If the backend later renames total to totalCents and changes its type to an integer, this code keeps compiling. It just silently returns undefined for order.total everywhere, forever, until someone notices the bug in production.

// Schema-generated: the type comes from the API's own published spec
// (illustrative — the actual generator/tooling varies by project)
import type { paths } from "./generated/api-types"; // produced from the API's OpenAPI spec

type OrderResponse = paths["/orders/{id}"]["get"]["responses"]["200"]["content"]["application/json"];

async function getOrder(id: string): Promise<OrderResponse> {
  const res = await fetch(`/api/orders/${id}`);
  return res.json() as OrderResponse;
}

Regenerating generated/api-types after the backend's rename immediately turns every place order.total was read into a real compile error — the exact opposite of the hand-written version silently drifting.

What people usually miss

Watch out

• as SomeType is a promise to the compiler, not a check. TypeScript trusts a type assertion unconditionally — it performs zero runtime verification that the actual value matches, which is exactly the gap codegen and end-to-end approaches close at compile time, and only real runtime validation closes at request time.
• Codegen closes the drift gap, not the runtime-trust gap. Regenerated types keep the client's compile-time understanding in sync with the API's published contract — they don't verify that any specific response, right now, actually matches that contract.
• End-to-end approaches trade independence for tightness. Sharing types directly between server and client usually means the two are more coupled in tooling and deployment than a fully independent REST API — genuinely worth it when one team owns both sides and can coordinate releases together.
• None of this replaces validating a truly external API at runtime. A third-party API you don't control can't hand you compile-time guarantees at all — its response has to be checked when it actually arrives, which is a different problem than keeping your own types in sync with your own backend.

Why this matters in interviews

"How do you keep your frontend's types in sync with a backend that keeps changing?" is a real question that tests whether a candidate knows as SomeType is an unchecked promise, and can name concrete alternatives — schema-driven codegen, end-to-end type sharing, and runtime validation — along with which one actually fits an external API versus one your own team controls.