How to Type API Responses in TypeScript

Every frontend developer has been there: you fetch data from an API, access a property, and get undefined at runtime — even though TypeScript never complained. The problem isn’t your code. It’s that TypeScript’s type system only operates at compile time. It has no idea what your API actually returns.

This article covers practical patterns for typing API responses in TypeScript, from defining basic interfaces to runtime validation and contract-driven type generation.

Why TypeScript Can’t Protect You at Runtime

When you call response.json(), TypeScript typically treats the result as unknown (or sometimes any, depending on environment typings). That means you can cast it to whatever you want — and the compiler will trust you completely.

// ❌ TypeScript trusts this cast blindly
const data = (await response.json()) as User
console.log(data.email) // Could be undefined at runtime

This is the core boundary to understand: TypeScript typed API responses give you compile-time safety, but they don’t validate the actual JSON your API returns. If the shape changes, TypeScript won’t know.

Defining Types for Expected Response Shapes

The first step is giving structure to what you expect. Use interfaces or type aliases to describe the response shape:

interface User {
  id: string
  name: string
  email: string
}

For consistent APIs, a generic wrapper handles both success and error states cleanly:

type ApiResponse<T> =
  | { status: "ok"; data: T }
  | { status: "error"; message: string }

This discriminated union pattern is more transparent than a single type with many optional fields. When you check status, TypeScript narrows the type automatically — no extra guards needed.

Typing Fetch Responses with a Generic Wrapper

Typing fetch responses in TypeScript is cleaner with a reusable helper:

async function apiFetch<T>(url: string): Promise<T> {
  const response = await fetch(url)
  if (!response.ok) throw new Error(`HTTP error: ${response.status}`)
  return response.json() as Promise<T>
}

// Usage
const user = await apiFetch<User>("/api/users/1")

This keeps your call sites clean while making the expected shape explicit. The same pattern works with Axios or any other HTTP client.

Runtime Validation: Closing the Gap

Type assertions like as User are a promise to the compiler, not a guarantee. For untrusted external data — third-party APIs, user-generated content, or any response you don’t fully control — you need runtime validation.

Zod is the most widely used option. You define a schema, parse the response, and get a fully typed result:

import { z } from "zod"

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})

type User = z.infer<typeof UserSchema> // Derived from schema

const data = await response.json()
const user = UserSchema.parse(data) // Throws if shape is wrong

The key benefit: your TypeScript types and your runtime validation stay in sync because they derive from the same source of truth.

Alternatives worth knowing:

• Valibot — smaller bundle, similar API to Zod
• ArkType — highly performant, TypeScript-native syntax

Use .parse() when you want to throw on invalid data, or .safeParse() when you want to handle errors gracefully without exceptions.

Contract-Driven Typing with OpenAPI

If your API has an OpenAPI specification, you can generate TypeScript types automatically using openapi-typescript:

npx openapi-typescript ./api-spec.yaml -o ./types/api.d.ts

This approach keeps your types in sync with your API documentation. It’s complementary to runtime validation — generated types handle the compile-time layer, while Zod or Valibot handle the runtime layer.

Choosing the Right Approach

Conclusion

TypeScript gives you structure and autocomplete, but it can’t validate what arrives over the network. For APIs you trust, a well-defined interface and a typed fetch wrapper are enough. For external or unpredictable data, pair your types with a runtime validator like Zod. When you have an API spec, generate your types from it. These approaches aren’t competing — they work best together.

FAQs

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.