The previous lesson in this module showed how the browser can keep small pieces of data for you between page loads. This lesson looks at the other side of the story, which is asking a server for data that your page does not have yet. The next lesson in this module takes the JSON that arrives and turns it into a page that reacts to failure.
The previous lesson in this module covered "localStorage and sessionStorage Done Right", and the next lesson in this module is about "Consuming JSON APIs and Their Error Shapes".
fetch() is JavaScript's built-in way of making HTTP requests, and it needs no library at all. It returns a promise for a response object, the response object gives you the status and the headers, and a second step reads the body. Once you understand that two-step shape, sending data, checking for failure, and cancelling a request that hangs all become straightforward.
What does fetch actually return?
A call to fetch() returns a promise immediately, before any bytes have arrived. When that promise resolves you get a Response object. The response knows the status code, the headers, and the URL that the request ended up at, but it does not know the body yet, because the body is still arriving over the network.
const response = await fetch('/api/products?limit=2');
console.log(response.status); // 200
console.log(response.ok); // true
console.log(response.headers.get('content-type')); // application/json
const data = await response.json();
console.log(data.total); // 2
Because fetch returns a promise, top-level await needs a module or an async function around it. In the browser you put the code in a <script type="module"> tag, and on a server you use an async function or an ES module. A script loaded the old way has no top-level await, and that is one of the more confusing errors you can meet while learning this.
Why is reading the body a separate step?
The body might be JSON, might be plain text, might be a stream of bytes, or might not exist at all. The response object therefore does not guess. You ask for the shape that you expect with response.json(), response.text(), response.blob(), or response.arrayBuffer(). Each of those returns a promise, and each of them can be read exactly once.
// This is wrong: response.json() returns a promise and it was never awaited.
const response = await fetch('/api/products');
const data = response.json();
console.log(data.total); // undefined
// This is right: the body is read in its own step.
const second = await fetch('/api/products');
const parsed = await second.json();
console.log(parsed.total); // 2
Calling response.json() twice on the same response throws an error, because the body has already been consumed. If you need the parsed data in two places, then store the parsed value rather than the response.
How do you send data with fetch?
The second argument is the options object. The three parts that you will use most are method, headers, and body. A request body has to be text, so a JSON object is stringified first.
const response = await fetch('/api/orders', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
productId: 42,
quantity: 3,
}),
});
console.log(response.status); // 201
const order = await response.json();
console.log(order.id, order.status); // 1042 created
Two details catch people out here. First, the Content-Type header tells the server how to read the body, and without it a server may try to parse your JSON as form data and fail. Second, GET and HEAD requests cannot carry a body at all, so putting one there is an error rather than a quiet no-op.
How do you check whether the request worked?
A network failure rejects the promise, but an HTTP error status does not. A 404 or a 500 arrives as a perfectly successful fetch, and only the status code says that something went wrong. This trips up almost everybody once, because the code looks like it worked.
Rather than repeat that check in every place, wrap it in one function that throws when the status is bad.
// api.js
export async function requestJson(url, options) {
const response = await fetch(url, options || {});
if (!response.ok) {
const problem = await response.text();
throw new Error('HTTP ' + response.status + ' - ' + problem.slice(0, 120));
}
return response.json();
}
// app.js
import { requestJson } from './api.js';
try {
const products = await requestJson('/api/products');
console.log(products.total); // 2
} catch (error) {
console.error(error.message); // HTTP 404 - plus the server's error body
}
response.ok is true for any status in the 200 range, which covers 200, 201, and 204. Reading the error body as text and putting only the first 120 characters into the message keeps a huge HTML error page out of your logs.
How do you stop a request that hangs?
A server that never answers leaves the promise pending forever, and a spinner on the screen forever with it. fetch supports an abort signal, and the simplest version of that is a deadline.
// A deadline that the browser enforces for you.
try {
const response = await fetch('/api/slow-report', { signal: AbortSignal.timeout(3000) });
console.log(response.status);
} catch (error) {
console.log(error.name); // TimeoutError
}
// An AbortController that you can cancel yourself.
const controller = new AbortController();
const timer = setTimeout(function () { controller.abort(); }, 3000);
try {
await fetch('/api/slow-report', { signal: controller.signal });
} catch (error) {
console.log(error.name); // AbortError
} finally {
clearTimeout(timer);
}
The controller version is the one that you want for anything user-driven, because the same signal can be aborted when the user navigates away or starts a newer request that makes the old one pointless. Two details are worth noting. An aborted request rejects with an error whose name is AbortError or TimeoutError, so a blanket catch will treat a cancellation the same as a real failure. And the browser does send the request anyway, it simply stops waiting for the answer.
Why does a request work in a test but fail in the browser?
Most fetch calls are same-origin, which means that the page and the API are served from the same host and the browser lets them through. Call a different host and the browser applies the same-origin policy. The server has to agree by sending an Access-Control-Allow-Origin header, and if you want cookies sent along as well then you also need Access-Control-Allow-Credentials and a specific origin instead of the wildcard.
// Same origin: the browser sends the page's cookies by default.
const same = await fetch('/api/me', { credentials: 'same-origin' });
console.log(same.status); // 200
// Cross origin: the server must allow this origin and allow credentials.
// Point this at a second origin to watch the CORS handshake:
// await fetch('https://api.example.com/me', { credentials: 'include' });
Some requests trigger a preflight. The browser first sends an OPTIONS request asking whether the real request is allowed, and it only sends the real request if the answer says yes. A GET with no extra headers is a simple request and skips that step, while a POST with a JSON content type, a custom header, or a method other than GET usually does not. When a request fails in the browser but succeeds in a terminal, the browser console almost always shows the preflight and the server's response headers, and that is where the answer is.
What to remember about fetch
- fetch returns a promise for a response, the body is read in a second step, and it can only be read once.
- An HTTP error status does not reject the promise, so check
response.okyourself, ideally inside a shared helper. - Send JSON with
method,headers, and aJSON.stringifybody. - Always give a request a deadline, and
AbortSignal.timeout(ms)covers the simple case. - Cross-origin requests are subject to CORS, so the server has to allow your origin before the browser hands you the response.
Try it yourself: Run a tiny local server that answers GET /api/products with JSON, and then point the first block at it. Add a POST /api/orders route that echoes the body back, and confirm that the third block prints 1042 created. Then change that route to return a 500 and watch how the error message in the fourth block appears only because you checked response.ok. Remove that check and the very same call starts to look like a success.