fetch & JSON

Requests, replies, and fetch

Web pages often need data from a server: a user's profile, a list of products, or today's weather. The page asks for the data, and the server sends it back. fetch is the browser function that does the asking.

You give fetch an address, called a URL, such as /api/users/42. You can also give it some settings. fetch sends a request to that address. The server sends back a response.

The trip over the network takes time, so fetch can't give you the response straight away. It gives you a Promise: an object that will hold the result later. You wait for it with await. When it is ready, you get a Response object.

The most common job is to ask a server for JSON. JSON is data written as text, like {"name":"Ada"}. The job has three steps:

1. Wait for the Response with await fetch(url).
2. Check whether the server says the request worked.
3. Wait again, with await response.json(), to read the JSON and turn it into a JavaScript object.

A Promise resolves when it finishes with a result. It rejects when it finishes with an error. Here is the most important fact in this lesson: the Promise from fetch resolves whenever the server replies. It resolves even when the reply says "404 Not Found". It rejects only when no reply reaches your code, for example when you are offline.

HTTP is the set of rules that browsers and servers use to talk. Web pages, JSON data, and images all travel with HTTP. The main rule is simple: the browser sends one request, and the server sends back one response.

Every request has a method. The method says what you want. GET means "give me this". POST means "here is something new to save".

A request and a response have the same three parts. Read the table one row at a time: each row is one part, first in the request, then in the response.

The status code is a three-digit number. Its first digit tells you its group. The table below lists each group, what it means, and codes you will see often.

In JavaScript, a Response object shows these parts as properties:

• status: the status code, such as 404.
• statusText: the words after the code, such as Not Found. Newer versions of HTTP often leave it empty, so don't rely on it.
• ok: true when the status is from 200 to 299.
• headers: the extra notes.
• url: the final address the response came from.
• redirected: true when fetch followed a redirect to get here.
• type: a word that says how the response was fetched, such as "basic" for your own site.

You can make a Response yourself with new Response(body, options). That is handy for practice, because you don't need a server. The code below makes one with status 201 and one header.

const response = new Response("hello", {
  status: 201,
  statusText: "Created",
  headers: { "X-Request-Id": "abc-123" },
});

console.log(response.status);
console.log(response.headers.get("x-request-id"));
console.log(response.headers.get("content-type"));

The three lines print 201, abc-123, and text/plain;charset=UTF-8. Line 9 asks for content-type, which the code never set. The body is a string, so Response adds a plain-text type by itself. A header that is really missing gives null.

The shortest form is await fetch(url). With no settings, fetch:

• uses the GET method,
• follows redirects for you,
• sends cookies only to your own site. A cookie is a small piece of data the browser keeps for a site, such as who is logged in. This setting is called credentials: "same-origin".

"Your own site" means the same origin: the same scheme, domain, and port as the page, such as https://example.com. The next lessons cover request settings, caching, and CORS.

1async function carefulFetch(url) {2  try {3    const response = await fakeFetch(url);4    console.log("resolved", response.ok, response.status);5 6    if (response.status === 204) {7      console.log("no body to parse");8      return null;9    }10 11    const type = response.headers.get("content-type") || "";12    if (!type.includes("application/json")) {13      throw new Error("Expected JSON");14    }15 16    const data = await response.json();17    if (!response.ok) {18      throw new HttpError(response.status, data.message);19    }20    return data;21  } catch (error) {22    console.log("caught", error.name);23    throw error;24  }25}

fakeFetch stands in for fetch on this page; the note below explains why. HttpError is an error class this lesson made: an Error that also holds the status. Read the function in this order:

1. Line 3 waits for the Response.
2. Line 6 checks for status 204, which means "no content". There is no body to read, so the function stops there.
3. Lines 11 to 14 check the Content-Type header. If the server didn't send JSON, the function throws an error.
4. Line 16 waits a second time, to read the body as JSON.
5. Lines 17 to 19 handle a bad status. The function throws an HttpError, so the code that called it knows something went wrong.
6. Line 21 catches any error, prints its name, and throws it again for the caller.

Headers are like a list of named notes. Read one with response.headers.get(name). You get the value as a string, or null if that header is missing. Header names ignore upper and lower case.

const response = new Response("tea", {
  headers: { "Content-Type": "text/plain; charset=utf-8" },
});

console.log(response.headers.get("content-type"));

Line 2 writes the name as Content-Type, with capitals. Line 5 asks for content-type, all lower case, and still finds it. It prints text/plain; charset=utf-8.

Search boxes and filters send the user's words in the URL, after a ?. This part of the URL is called the query string. Don't glue it together yourself. Spaces and symbols such as & have special meanings in a URL. URLSearchParams writes them safely for you.

const params = new URLSearchParams({
  q: "green tea",
  page: "2",
});

console.log("/api/search?" + params);

Lines 1 to 4 make two named values, q and page. Line 6 turns them into text and adds it after ?. It prints /api/search?q=green+tea&page=2. The space became a +.

const params = new URLSearchParams({ q: "tea & cake" });
const url = new URL("https://example.test/api/search");
url.search = params;

console.log(url.href);

Line 2 makes a URL object from a full address. Line 3 puts the query string into its search part. Line 5 prints https://example.test/api/search?q=tea+%26+cake. The & in tea & cake became %26, so it stays part of the search words. A plain & would start a new value.

response.ok is true or false. It is true when the status is from 200 to 299, and false for every other status. That is all it checks. It doesn't check that the body is valid JSON. It doesn't check that the data is what your app wanted.

1async function carefulFetch(url) {2  try {3    const response = await fakeFetch(url);4    console.log("resolved", response.ok, response.status);5 6    if (response.status === 204) {7      console.log("no body to parse");8      return null;9    }10 11    const type = response.headers.get("content-type") || "";12    if (!type.includes("application/json")) {13      throw new Error("Expected JSON");14    }15 16    const data = await response.json();17    if (!response.ok) {18      throw new HttpError(response.status, data.message);19    }20    return data;21  } catch (error) {22    console.log("caught", error.name);23    throw error;24  }25}

Pick 404, then 500, and press Run. The fetch Promise still resolves, because the server replied. Your code decides what happens next. A common choice is to read the error message from the JSON body, then throw a custom error that holds the status.

When fetch resolves, the body may still be arriving. So response.json() returns another Promise, and you await it a second time. It reads the whole body and turns the JSON text into a JavaScript object.

response.json() can reject even when fetch worked:

• The body is not valid JSON. It rejects with SyntaxError.
• There is no body, as with status 204. There is nothing to read, so it also rejects with SyntaxError.
• The body was already read. It rejects with TypeError.

Step through loadUser below. It asks the pretend server for user 42 and returns the user's name. Try each server answer:

• With 200, the function reaches line 9 and returns "Ada".
• With 404, fetch resolves, but the function stops at line 5 and throws.
• With a network error, fetch rejects, so the function stops at line 2.

1async function loadUser(id) {Run2  const response = await fakeFetch("/api/users/" + id);3 4  if (!response.ok) {5    throw new HttpError(response.status, "User not found");6  }7 8  const user = await response.json();9  return user.name;10}

A body can be read only once. The first read uses it up, and response.bodyUsed becomes true. A second read rejects with TypeError.

Try both buttons in the demo: read twice fails, and clone first works.

1const response = new Response(JSON.stringify({ ok: true }), {2  headers: { "Content-Type": "application/json" },3});4 5const first = await response.json();6console.log(first.ok);7 8const second = await response.json();9console.log(second.ok);

Every body method follows the same one-read rule. Each one reads the body in a different form:

• json() reads JSON and gives an object.
• text() reads plain text or HTML and gives a string.
• blob() reads a file, such as an image.
• arrayBuffer() reads raw bytes.
• formData() reads form fields.

If two parts of your code both need the body, call response.clone() before either one reads it. The copy gets its own body.

Pick the method that matches the data. For plain text, use text(). Calling json() on plain text would reject, because the text is not JSON.

const response = new Response("plain text");

console.log(await response.text());

The body is the text plain text, so line 3 prints exactly that. After this read, the body is used up. Calling json() on the same response now would reject.

const response = new Response("{ bad", {
  headers: { "Content-Type": "application/json" },
});

response.json().catch((error) => console.log(error.name));

The Response is fine, but its body, { bad, is not valid JSON. .catch() runs a function when a Promise rejects. Here, line 5 prints SyntaxError. This is a different failure from a network error, where fetch itself rejects.

The pretend server gives the same result every time, which is good for learning. But fetch is a real browser tool, so let's run it for real. These four requests are safe, and none of them contacts another site:

• this page,
• a page on this site that doesn't exist,
• a data: URL, which holds its JSON inside the address itself, so no server is needed,
• a cancelled blob URL. A blob URL is an address for data kept in your browser's memory. Once it is cancelled, it points at nothing.

1await fetch(location.href);2await fetch("/javascript/this-page-does-not-exist");3await fetch('data:application/json,{"name":"Ada"}');4const url = URL.createObjectURL(new Blob(["gone"]));5URL.revokeObjectURL(url);6await fetch(url);

What each button shows:

• fetch this page: a response can hold HTML, not JSON.
• missing page (404): a missing page gives a response with ok: false.
• data URL JSON: json() can read JSON with no server at all.
• cancelled blob URL: when nothing can answer, fetch rejects with TypeError.

Many people think every bad status makes fetch reject. It doesn't. A response with 404, 429, or 500 is still a response. These are HTTP errors: the server replied, and the reply says something went wrong.

fetch rejects only when there is no response your code can use. These are network errors:

• You are offline, or the server can't be found.
• The URL is not valid.
• The browser blocks the response because of CORS, a safety rule explained below.
• The request is cancelled, which is also called aborted. fetch then rejects with the reason given for the cancel. Often that is an AbortError.

CORS is a browser safety rule. It decides whether a page may read responses from another site. You'll learn it two lessons from now. For now, remember one thing: when the browser blocks a response from another site, your code can't see its status or body. fetch rejects with TypeError.

A timeout also makes fetch reject. A timeout is a time limit. AbortSignal.timeout(1000) makes a signal: an object that cancels a request when it fires. This one fires by itself after 1000 milliseconds, which is 1 second. So the request can't wait forever.

const signal = AbortSignal.timeout(1000);

console.log(signal.aborted);
console.log(signal instanceof AbortSignal);

The signal has not fired yet, so line 3 prints false. Line 4 prints true, because it is an AbortSignal. You can pass it to fetch as the signal setting. The cancellation lesson shows how to combine signals and handle the timeout error.

const signal = AbortSignal.timeout(1000);
const options = { signal };

console.log(options.signal === signal);
console.log(signal.aborted);

Line 2 puts the signal into a settings object. Making this object doesn't send anything. It only holds the signal, ready for fetch(url, options). Line 4 prints true, because it is the same signal. Line 5 prints false, because a second hasn't passed yet.

Pages fetch JSON whenever they need fresh data. For example, when they:

• load a user's profile,
• save a to-do item,
• search while the user types,
• refresh a dashboard,
• send a contact form.

Pages read JSON often, and they send it often too.

A small helper function keeps the status check in one place. This one takes the fetch function as a parameter. In a test, you can pass a stand-in that returns a Response you made yourself. Then the test gets the same result every time, with no live server.

async function getJSON(url, fetcher = fetch) {
  const response = await fetcher(url);
  if (!response.ok) {
    throw new Error("HTTP " + response.status);
  }
  return response.json();
}

const fetcher = () => Promise.resolve(new Response(
  JSON.stringify({ name: "Asha" }),
  { headers: { "Content-Type": "application/json" } },
));

console.log((await getJSON("/api/user", fetcher)).name);

Line 2 waits for the response. Lines 3 to 5 throw an error if the status is not OK. Only then does line 6 read the JSON. Lines 9 to 12 make a stand-in fetcher that returns a real Response holding {"name":"Asha"}. So line 14 prints Asha.

1const todo = { title: "Learn fetch", done: false };2 3await fetch("/api/todos", {4  method: "POST",5  headers: { "Content-Type": "application/json" },6  body: JSON.stringify(todo),7});

A JSON request body is text. To send JSON:

• Use a method that allows a body, such as POST, PUT, or PATCH (line 4). GET requests can't have a body.
• Set the Content-Type header to application/json (line 5). It tells the server how to read the body.
• Turn your object into JSON text with JSON.stringify(todo) (line 6).

const todo = { title: "Buy tea", done: false };
const request = new Request("/api/todos", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(todo),
});

console.log(request.method);
console.log(request.headers.get("content-type"));
console.log(await request.text());

new Request() takes the same address and settings as fetch, but it only builds the request. It doesn't send it. Lines 8 to 10 print POST, application/json, and {"title":"Buy tea","done":false}. The body really is text.

• "fetch rejects on 404." No. It resolves with a response whose ok is false.
• "response.json is the JSON." No. It is a method. Calling it returns a Promise for the data.
• "ok means my app is happy." No. It only means the status is from 200 to 299.
• "Every response has JSON." No. A response can hold HTML, a file, invalid text, or nothing at all, as with 204.
• "I can read the body again and again." No. A body can be read once. Call clone() first if you need two reads.
• "Header names care about upper and lower case." No. headers.get("content-type") finds Content-Type.

The table compares three Promises that people often mix up. Read across a row to see when that Promise resolves, and why it usually rejects.

Key takeaways

• fetch(url, options) returns a Promise. It resolves with a Response when the status and headers arrive.
• A bad status such as 404 or 500 doesn't make fetch reject. Check response.ok and response.status yourself.
• response.json() is a second wait. It reads the body once, and it can reject.
• fetch rejects only when no usable response arrives: a network problem, a CORS block, a bad URL, or a cancel.
• To send JSON, use a method such as POST, set Content-Type: application/json, and send JSON.stringify(data).

Final definition: fetch sends an HTTP request and resolves with a Response. Your code checks the status, then reads the body once with the right method, such as json().

Up next: Requests in depth. You'll learn more about methods, headers, bodies, and the Request and Response objects.