Building a Type-Safe API Client in TypeScript: Beyond Axios vs Fetch

I always liked to make requests through Axios and I think there is no alternative yet

Ok, since the one other commenter here and the author don't seem to have seen something better, I'll be the light-bringer into this darkness that Axios really is.

Killing the Reasons Why Axios is the Winner

I'll go one at a time.

Automatic JSON parsing (fetch makes you call .json() every time)

I don't need a 2MB package for one line of code.

Built-in error handling (no more checking response.ok manually)

This is bad. I have blogged about this. Long story short: You're driving logic via thrown errors. In other words: You are using try..catch as a branching statement. The worst part: It is around a 40% performance hit in Chromium (don't know Firefox, Opera, etc.).

Interceptors for global logic (auth tokens, logging, whatever)

It takes more code to write an Axios interceptor than it takes to do the same job using fetch.

Request cancellation that actually works

Are you trying to imply that cancellation in fetch doesn't? Because you would be wrong. If you're not trying to imply this, then what is this all about?

Global config that applies everywhere

I don't need a 2MB package to get this.

The ApiClient

Now to the ApiClient class. I copied the code in a VS Code window. It is 62 lines in size, and doesn't include shortcut functions for PUT, DELETE, PATCH or HEAD. Now let me show you code that does all that (except for error handling) using the dr-fetch NPM package:

import { DrFetch, type FetchFnInit, type FetchFnUrl, setHeaders } from "dr-fetch";

type ValidationError = {
    code: number;
    message: string;
}

function myFetch(url: FetchFnUrl, init?: FetchFnInit) {
    init ??= {};
    const token = localStorage.getItem('authToken');
    if (token) {
        setHeaders(init, { Authorization: `Bearer ${token}` });
    }
    return fetch(url, init);
}

export const apiClient = new DrFetch(myFetch)
    .for<400, ValidationError[]>()
    .build();

This is 19 lines of code. It is also not missing any shortcut verb functions. It provides GET, POST, PUT, PATCH, DELETE and HEAD shortcut methods. Furthermore, it pre-types HTTP 400 responses. TypeScript will tell you that inside if (response.status === 400), response.body will be an array of validation error objects. More on typing below.

About the Error Handling

This is the code that doesn't have equivalency in the above counter-example:

    // Handle errors consistently
    this.client.interceptors.response.use(
      (response) => response,
      (error) => {
        const apiError = {
          message: error.response?.data?.message || error.message,
          status: error.response?.status || 500,
          code: error.response?.data?.code,
        };
        return Promise.reject(apiError);
      }
    );

This is a hot mess. Let's talk about it.

First and foremost, because Axios throws on non-OK responses, which is a very bad thing to do, we could potentially be getting response bodies in response.data that don't have a message property because, perhaps, not all non-OK HTTP responses carry a JSON with said property. For example, HTTP status code 503 (temporarily unavailable) commonly returns text, not JSON.

The above also lacks TypeScript, which is surprising given the title of the article. And why isn't it typed? Because Axios doesn't have the ability to type response bodies depending on the HTTP status code of the response. However, and I don't know if you noticed, dr-fetch CAN type the body differently according to the HTTP response code.

We can do things like this:

const response = apiClient
    .for<200 | 201, { id: number; name: string }>() // Same type for 200 OK and 201 CREATED
    .for<503, string>()
    .put('/api/some-endpoint', {
        id: 1,
        name: 'Updated Name'
    });

if (response.ok) {
    setUpdatedData(response.body); // Body is fully typed as { id: number; name: string }
}
else if (response.status === 400) {
    const errors = response.body; // Body is fully typed as ValidationError[]
    console.error('Validation errors:', errors);
} else if (response.status === 503) {
    console.error('Service unavailable:', response.body); // Body is fully typed as string
} else {
    console.error('Unexpected error:', response.status);
}

All the above gets full Intellisense by virtue of TypeScript's type narrowing mechanism.

Now back to your code snippet again: You write a response interceptor that is powered by a catch block inside Axios to create a new object that is thrown as well, incurring again in the expensive callstack unwinding operation. Basically, another 40+% performance hit, on top of the one that Axios makes you incur in the first place.

Finally, your shortcut functions show an awful thing to do: Catching errors just to throw them again.

Both get and post in your code do try { ... } catch (error) { throw error; }. Why? If you're not doing anything with the error, you don't add a try..catch block. Yes, not exactly code in the "handle errors consistently" part of your code, but I suppose these are related and why I mention these here.

This is why the error handling was omitted from the equivalent API client I presented: The code you presented has inherent flaws that Axios is incapable of coping with, alongside an unnecessary thing to do, which you're presenting as the epitome and pinnacle of how to fetch data "correctly".

But not only this: By being able to type the body depending on the HTTP response, we can create a better user interface: We could show the user validation error messages nicely, with a simple else if (response.status === 400). With the error standardization thing you show, these validation error messages are effectively being discarded.

Summarizing:

• Axios throws on non-OK responses. This incurs in a 40+% performance hit.
• The response interceptor incurs in an extra 40+% performance hit.
• The code cannot possibly be free of TypeScript errors: TypeScript must be complaining about the message property not existing in response.data.
• Axios is incapable of typing the body of a response depending on the HTTP status code received.
• The presented code discards potentially useful response bodies, just because they came in non-OK HTTP responses.
• 62+ lines of code using axios, a package with thousands of lines of code, that can be beaten with 19 LOC using dr-fetch, a 421-LOC NPM package.

Conclusion

With axios you write more code for less value. If there's one popular package that I personally think should be archived, is axios.

I suppose that now comes the list of many, many other things Axios can do. Let's hear them, I suppose.