Fetch API: Making Basic Network Requests

Why it exists

Web applications need to communicate with servers without reloading the page. The original method, XMLHttpRequest, was complex and callback-based. The Fetch API was created to provide a modern, promise-based, and more flexible interface for network requests.

The mental model

Think of fetch() as a two-step delivery process. First, you call fetch(url). This immediately returns a Promise that represents the attempt to make the request. This promise resolves into a Response object as soon as the server sends back its headers. This Response is just the "shipping notification," not the package itself. The second step is to unpack the package by calling a method on the response, like response.json(), which also returns a promise that resolves with the actual body content.

How it works

The fetch() method takes a URL as its first argument. It returns a Promise that resolves to a Response object. This object contains metadata like the status code (response.status) and headers. The body of the response is a stream and is not immediately available. To access it, you must call a parsing method like response.json() for JSON data or response.text() for plain text. Each of these methods returns another promise that resolves with the parsed body content.

When to use it

Use fetch() for nearly all modern client-side network requests. It's ideal for getting data from REST or GraphQL APIs, submitting data via POST requests (by providing an options object), and loading any resource asynchronously. It's available in the main browser window and in Web Workers, making it universally accessible.

When not to use it

The biggest footgun is that fetch() only rejects its promise on a network failure (like no internet connection), not on HTTP error statuses (like 404 Not Found or 500 Internal Server Error). You must always check the response.ok property to handle these cases. For cross-origin requests that need cookies, you must explicitly set the credentials: 'include' option. For very old browsers, you may need a polyfill.

One canonical example

To get user data from a JSON API, you first fetch the URL, then check if the response was successful, and only then parse the JSON body. A common pattern using async/await looks like this:

async function getUser() {
try {
const response = await fetch('https://api.example.com/users/1');
if (!response.ok) {
throw new Error(HTTP error! Status: ${response.status});
}
const user = await response.json();
console.log(user.name);
} catch (error) {
console.error('Fetch error:', error);
}
}

This example correctly checks response.ok before trying to use the data.