Fetching API Data with TypeScript: Using Type Assertions

Source: Dev.to

Understanding the Problem

When we fetch data from an API in JavaScript, we usually do something like:

const response = await fetch("https://randomuser.me/api/?results=3");
const data = await response.json();
console.log(data);

JavaScript doesn’t care about types. The code will run even if the API changes its structure or fields.

In TypeScript, response.json() returns any (or unknown depending on settings). TypeScript doesn’t know the shape of the data, so we can’t safely access nested properties without risking errors. This is where type assertions come in.

[Image: JSON structure returned by the RandomUser API]

[Image: JSON structure returned by the EscuelaJS Products API]

Using TypeScript Type Assertions

Type assertions tell TypeScript: “I know the structure of this data better than you do.”

[Image: Type assertion example]

Example

const data = await response.json();

const users = data as unknown as {
  results: {
    name: { first: string; last: string };
    email: string;
    picture: { large: string };
  }[];
};

• data is unknown after response.json().
• as unknown as { … } tells TypeScript: “Treat data as an object with a results array containing this exact structure.”

This allows us to safely access nested properties like results[0].name.first without TypeScript complaining. The double assertion (as unknown as) is sometimes needed when TypeScript is too conservative and refuses a direct conversion.

[Image: Double assertion illustration]

Mapping API Data to Your Own Types

Even after asserting the type, exposing the entire nested API structure throughout the app can be cumbersome. Instead, map the data to a simpler, internal type:

export type User = {
  name: string;
  email: string;
  picture: string;
};

return users.results.map(u => ({
  name: `${u.name.first} ${u.name.last}`,
  email: u.email,
  picture: u.picture.large,
}));

Now the rest of the app works with a clean, predictable User[] array, benefiting from proper typing and autocomplete support.

Why This Matters

Through this exercise, I realized how TypeScript helps in several ways:

• Prevent runtime crashes – TS catches mistakes before the code runs.
• Autocompletion / IntelliSense – Write code faster with fewer typos.
• Self‑documenting code – Types tell anyone reading the code exactly what data looks like.
• Safe refactoring – If a field is renamed or the API changes, TS will warn you.

Even small experiments like fetching users or products can teach you how typed async flows work in real projects.

Key Points

• TypeScript doesn’t magically know API data; we teach it using types or type assertions.
• Mapping API data to our own types makes apps safer and easier to work with.