Typing API Responses

A type is a claim you make about your own code, checked before the code runs. Server data arrives while the code is running, long after any checking happened.

So writing interface Expense does not make an API response an Expense. It states what you are expecting. Whether the response matches is a separate question, and one that nothing in TypeScript answers on its own.

The server can legitimately send something else. A field is renamed in a deployment. An optional property turns out to be null rather than absent. A proxy returns an HTML error page. A different version of the API is live than the one you tested against. None of these are exotic; they are ordinary Tuesday events on a system with more than one team working on it.

One way to hold the whole topic: your application has an inside and an outside. Inside, types are reliable, because the checker verified every line against them. Outside, nothing is known. Validation is the door between the two, and where you put that door decides whether the types inside are guarantees or assumptions.

interface Expense {
  id: string;
  description: string;
  amount: number;
  status: "draft" | "submitted" | "approved" | "rejected";
}

async function loadExpenses(employeeId: string): Promise<Expense[]> {
  const response = await fetch("/api/employees/" + employeeId + "/expenses");

  if (!response.ok) {
    throw new Error("Expenses request failed with status " + response.status);
  }

  // The only line that is not carrying its weight
  return (await response.json()) as Expense[];
}

// Somewhere else entirely, much later
const total = expenses.reduce((sum, expense) => sum + expense.amount, 0);

• The status check is right, and this function is better than most. The assertion is the weak point.
• response.json() returns Promise<any> — the values are genuinely unknown at that moment, and that is accurate.
• The assertion replaces that honest uncertainty with a specific claim. Nothing is checked. If the server renames amount to amountInPence, this line still succeeds.
• The failure surfaces in the reduce, where every amount is undefined and the total is NaN. The reduce is correct code. It will be read carefully, several times, by someone who has no reason to suspect the fetch.
• A NaN total is the good outcome. A missing status is worse, because the row renders with an empty badge and looks plausible, so the wrong data is trusted.

const STATUSES = ["draft", "submitted", "approved", "rejected"] as const;

function isExpense(value: unknown): value is Expense {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  const candidate = value as Record<string, unknown>;

  return (
    typeof candidate.id === "string" &&
    typeof candidate.description === "string" &&
    typeof candidate.amount === "number" &&
    Number.isFinite(candidate.amount) &&
    typeof candidate.status === "string" &&
    (STATUSES as readonly string[]).includes(candidate.status)
  );
}

async function loadExpenses(employeeId: string): Promise<Expense[]> {
  const response = await fetch("/api/employees/" + employeeId + "/expenses");

  if (!response.ok) {
    throw new Error("Expenses request failed with status " + response.status);
  }

  const body: unknown = await response.json();

  if (!Array.isArray(body) || !body.every(isExpense)) {
    throw new Error("Expenses response did not match the expected shape");
  }

  return body;
}

• value is Expense in the return position makes this a type predicate. When it returns true, the checker treats the value as an Expense from then on — the narrowing is earned by the checks rather than asserted.
• The parameter is unknown, so nothing can be read from it until its shape has been established. That is what forces the object check first.
• The one assertion here is to Record<string, unknown>, after confirming the value is a non-null object. It claims only that properties may be read and each is still unknown, so every field is checked individually. This is the narrow case where an assertion is reasonable.
• Number.isFinite rejects NaN and Infinity, which typeof number does not. An amount of NaN passes a typeof check and then poisons every total it touches.
• The status is checked against the actual allowed values, so a new status the frontend does not understand is caught here rather than rendering as a blank badge.
• The function now fails at the boundary, with a message naming the boundary. That is the whole win: the error appears where the bad data entered, not three components downstream.