How to type third-party API responses in TypeScript (without lying to your compiler)

You add TypeScript to a project, turn on strict, fix every red squiggle, and feel safe. Then a third-party API quietly changes a field from a number to a string, your app explodes in production, and TypeScript never said a word.

That gap surprises people, so it's worth saying plainly: TypeScript checks your code, not the data your code receives at runtime. The moment a value crosses the network boundary, your types are a promise nobody is enforcing. This article walks through how to type API responses honestly — from the quick approaches that only look safe, to the ones that actually hold up when the data misbehaves.

The starting point: fetch gives you nothing

Here's the shape of the problem. The built-in fetch returns a response whose .json() resolves to any:

const response = await fetch("https://api.example.com/users/1");

const user = await response.json(); // user: any

console.log(user.naem.toUpperCase()); // typo, no error, crashes at runtime

any switches type checking off. Every property access is allowed, including the typo. So the first instinct is usually to reach for a type assertion.

The trap: as assertions

This compiles, and it's tempting:

interface User {

  id: number;

  name: string;

  email: string;

}



const user = (await response.json()) as User;

console.log(user.name.toUpperCase());

Now your editor autocompletes user.name and the typo is caught. It feels solved. It isn't.

as is you telling the compiler "trust me, this is a User." The compiler stops arguing and assumes you're right. But nothing checks the actual JSON. If the API returns { "id": "1", "name": null }, TypeScript still believes name is a string, and user.name.toUpperCase() throws Cannot read properties of null in production — exactly the failure types were supposed to prevent.

A type assertion doesn't verify anything. It silences the one part of your stack that was being honest about not knowing.

Step one: generics for a reusable typed wrapper

Before we fix the runtime problem, let's at least stop repeating ourselves. A small generic wrapper lets each call site say what it expects:

async function getJson<T>(url: string): Promise<T> {

  const response = await fetch(url);

  if (!response.ok) {

    throw new Error(`Request failed: ${response.status}`);

  }

  return response.json() as Promise<T>;

}



interface User {

  id: number;

  name: string;

  email: string;

}



const user = await getJson<User>("https://api.example.com/users/1");

console.log(user.name.toUpperCase()); // user is typed as User

This is genuinely useful: the <T> flows through, so every caller gets a typed result without scattering assertions everywhere. The error handling lives in one place.

But be honest about what it does and doesn't do. That as Promise<T> inside the wrapper is the same assertion as before, just hidden one level down. The ergonomics improved; the runtime safety did not. The data is still unverified.

Step two: validate at the boundary with a schema

The real fix is to check the data once, at the edge where it enters your app, and only hand the rest of your code values that have actually been verified. A schema validation library like turns the spec into types.

Codegen's advantage is that the types are mechanically tied to the contract: when the API's spec changes and you regenerate, the new or removed fields show up as type errors across your codebase, pointing you straight at what broke. The tradeoff is that most codegen describes the shape at build time; it doesn't, by itself, validate the actual response at runtime. For untrusted or flaky sources, people often pair generated types with a runtime check at the boundary.

Which approach should you reach for?

There's no single winner — it depends on how much you trust the source and what the API gives you:

• 
  Internal API you control, low risk, want speed: a generic getJson<T> wrapper with hand-written interfaces is fine. Just know the runtime is unchecked.


• 
  Third-party or user-facing data, correctness matters: validate at the boundary with a schema (Zod or similar) and derive your types from it. This is the default I'd recommend for anything important.


• 
  API ships an OpenAPI or GraphQL schema: generate types from the contract, and add a runtime check at the edge if the data is untrusted.

Notice the through-line: the safest options all push verification to the boundary and keep a single source of truth for the type. Everything inside your app then works with data that's already been proven to match its type — which is the actual promise TypeScript was supposed to give you.

Takeaway

TypeScript types describe what your data should be. They don't make it so. For data you generate inside your own code, that's enough. For data arriving over the network, you need something that checks reality:

• Reach for generics to stop repeating type assertions, but don't mistake nicer ergonomics for safety.


• Avoid as on API responses — it silences the compiler instead of verifying the data.


• 
  Validate at the boundary with a schema and infer your types from it, so the type and the check can never drift apart.


• 
  Generate types from an OpenAPI or GraphQL contract when one exists, and validate at runtime when the source is untrusted.

Do that, and the next time an API quietly changes a field, you find out at the boundary with a clear error — not from a user, in production, three layers deep.