Requests in depth

What a request is made of

In the fetch lesson, a request was simple: ask a URL for data, check response.ok, and read the JSON. Real apps also save, change, and delete data. For that, a request needs more parts.

A request can say:

• which method to use: the action you want, such as "read" or "create".
• which headers to send: short notes about the request, such as "the data I send is JSON".
• which body to send: the data itself, such as a new todo.
• whether credentials may go along: the cookies and logins the browser has saved.
• how to use the browser's cache: its store of earlier replies.

This lesson doesn't talk to a real server on the internet. A server is the computer that keeps the data and answers requests. Here, a tiny pretend server lives inside the page and keeps a list of todos in memory. The function fakeFetch(input, init) works like fetch. It makes a real Request object, hands it to the pretend server, and gives back a real Response object. The response has a status code, a JSON body, and headers such as Location (where a new todo lives) and ETag (a version label).

An HTTP method is a word at the start of every request. It tells the server what you want to do. Each thing the server keeps, like one todo or the whole todo list, is called a resource. Each resource has its own URL, such as /api/todos/2. This style, where the URL names the resource and the method names the action, is called REST.

Two words help you describe methods:

• Safe: the method only reads. It doesn't change anything on the server.
• Idempotent: sending the same request many times leaves the server the same as sending it once.

These words matter when a request gets sent again. That happens when someone double-clicks a button, refreshes the page, or the network tries again.

1const methods = [2  ["PUT", "replace", true],3  ["PATCH", "partial change", "depends"],4  ["DELETE", "remove", true],5];6 7for (const [method, action, repeatable] of methods) {8  console.log(method, action, repeatable);9}

Each row in the methods list has three parts: the method, what it does, and whether repeating it gives the same result. Line by line:

• Line 2: PUT replaces a whole todo. Sending the same replacement twice gives the same todo, so it says true.
• Line 3: PATCH changes part of a todo, so it says "depends". A patch that sets completed: true gives the same result every time. A patch that says "add 1 to the counter" changes the result every time.
• Line 4: DELETE removes a todo. A second delete has nothing left to remove, so it says true.
• Lines 7 to 9 go through the list and print one line per method, such as PUT replace true.

The table below lists the common methods. Read each row as: this method usually does this; does it only read; and does repeating it give the same result?

So GET, HEAD, and OPTIONS are safe and idempotent. PUT and DELETE change data, so they are not safe. But they are idempotent. POST and PATCH are usually not idempotent: sending the same order twice can make two orders.

The playground below sends requests to the pretend server. The "Server data" line shows the todo list after each request. Try these in order:

1. GET /api/todos with no body.
2. POST /api/todos with the "new title" body.
3. PATCH /api/todos/2 with the "mark completed" body.
4. DELETE /api/todos/1.

1const response = await fakeFetch("/api/todos", {2  method: "POST",3  headers: {4    "Content-Type": "application/json",5    Accept: "application/json",6  },7  body: JSON.stringify({ title: "Pack a snack" }),8});9 10console.log(response.status);11console.log(response.headers.get("Location"));12console.log(await response.json());

One rule to know: a GET or HEAD request can't have a body. If you give it one, the Request constructor throws a TypeError.

Headers are short name-and-value notes sent with a request or a response. For example, Content-Type: application/json says "the body is JSON". JavaScript keeps headers in a Headers object. It has a few methods:

• append(name, value) adds one more value to a header.
• set(name, value) replaces every value the header had.
• get(name) reads a header. If it has several values, you get them joined with a comma.

Header names ignore upper and lower case. Content-Type, content-type, and CONTENT-TYPE are the same header.

1const headers = new Headers();2headers.append("Accept", "application/json");3headers.append("accept", "text/plain");4headers.set("Content-Type", "application/json");5 6console.log(headers.get("ACCEPT"));7console.log([...headers]);

Lines 2 and 3 add two values to the same header, Accept. Line 3 writes the name in lower case, but it is still the same header. Line 4 sets Content-Type. Line 6 reads ACCEPT and prints application/json, text/plain. Line 7 prints every header as a [name, value] pair, with the names in lower case.

1const headers = new Headers();2headers.append("Accept", "application/json");3headers.append("accept", "text/plain");4headers.set("Content-Type", "application/json");5 6console.log(headers.get("ACCEPT"));7console.log([...headers]);

Some headers belong to the browser. Your code shouldn't try to set Host (the server's name) or Cookie (saved login data). The browser decides what to send for those. The lab shows what your browser lets a Headers object store. But storing a header in the object doesn't mean the browser will send it.

JSON is a text format for data. To send JSON, you need three things:

• a method that can carry a body, such as POST.
• the header Content-Type: application/json, so the server knows the body is JSON.
• the data turned into text with JSON.stringify.

The JSON lesson explains why JSON is text and not a live object.

1async function createTodo(title) {2  const headers = new Headers();3  headers.set("Accept", "application/json");4  headers.set("Content-Type", "application/json");5 6  const body = JSON.stringify({ title });7  const response = await fakeFetch("/api/todos", {8    method: "POST",9    headers,10    body,11  });12 13  if (!response.ok) {14    const problem = await response.json();15    throw new Error(response.status + " " + problem.message);16  }17 18  const location = response.headers.get("Location");19  const todo = await response.json();20  return { location, todo };21}

Line by line:

• Lines 2 to 4 make a Headers object. Accept asks for JSON back. Content-Type says the body is JSON.
• Line 6 turns { title } into JSON text.
• Lines 7 to 11 send it to /api/todos with POST.
• Line 13 checks response.ok. If the server said no, line 14 reads the server's error message, and line 15 throws an Error.
• Line 18 reads the Location header. Line 19 reads the new todo. Line 20 returns both.

1async function createTodo(title) {Run2  const headers = new Headers();3  headers.set("Accept", "application/json");4  headers.set("Content-Type", "application/json");5 6  const body = JSON.stringify({ title });7  const response = await fakeFetch("/api/todos", {8    method: "POST",9    headers,10    body,11  });12 13  if (!response.ok) {14    const problem = await response.json();15    throw new Error(response.status + " " + problem.message);16  }17 18  const location = response.headers.get("Location");19  const todo = await response.json();20  return { location, todo };21}

Pick "empty title" or "duplicate title" above the replay. The request still reaches the pretend server, but the server says no: 422 for an empty title, and 409 for a title that already exists. The helper reads the server's JSON error message and throws an Error with it.

fetch can take a URL plus an options object. It can also take a ready-made Request object. A Request holds everything about one request: the URL, the method, the headers, the body, and the other options. You can build it now and send it later.

A Response holds the server's answer: the status code, the headers, and the body.

The body of a request or a response is a stream: data that arrives in pieces and can be read only once. Sometimes you need to read a body twice, for example once to log it and once to use it. Then call clone() first. clone() makes a copy with its own body. You met the "read once" rule with response.json() in the fetch lesson. Here it applies to requests too.

1const request = new Request("/api/todos", {2  method: "POST",3  headers: { "Content-Type": "application/json" },4  body: JSON.stringify({ title: "Clone me" }),5});6 7const copy = request.clone();8console.log(await request.text());9console.log(await copy.json());10 11const response = Response.json(12  { saved: true },13  { status: 201, headers: { Location: "/api/todos/3" } },14);15console.log(response.status);16console.log(response.headers.get("content-type"));

1const request = new Request("/api/todos", {2  method: "POST",3  headers: { "Content-Type": "application/json" },4  body: JSON.stringify({ title: "Clone me" }),5});6 7const copy = request.clone();8console.log(await request.text());9console.log(await copy.json());10 11const response = Response.json(12  { saved: true },13  { status: 201, headers: { Location: "/api/todos/3" } },14);15console.log(response.status);16console.log(response.headers.get("content-type"));

Line 7 clones the request before anything reads it. Line 8 reads the original as text. Line 9 reads the copy as JSON. Lines 11 to 14 build a 201 response with Response.json. Line 15 prints 201. Line 16 prints its content-type header, which is application/json.

1(async () => {2const request = new Request("https://example.test/todos", {3  method: "POST",4  headers: { Accept: "application/json" },5  body: "title=Pack%20tea",6});7 8console.log(request.method);9console.log(request.headers.get("accept"));10console.log(await request.text());11})();

Lines 1 and 11 wrap the code in an async function, so it can use await. Line 2 builds a POST request. Nothing is sent to a server. Line 8 prints POST. Line 9 asks for accept in lower case and still finds application/json. Line 10 reads the body as text and prints title=Pack%20tea. (%20 is how a space is written in this URL-style text.) After line 10, the body is used up.

1const missing = new Response("missing", {2  status: 404,3  statusText: "Not Found",4});5const broken = new Response("failed", { status: 500, statusText: "Server Error" });6 7console.log(missing.status, missing.statusText, missing.ok);8console.log(broken.status, broken.statusText, broken.ok);

Lines 1 to 5 build two responses by hand: a 404, which means "not found", and a 500, which means "the server failed". Line 7 prints 404 Not Found false. Line 8 prints 500 Server Error false. ok is true only for status codes from 200 to 299. statusText is a short reason in words. Check the number, not the words.

1const response = Response.redirect("https://example.test/login", 302);2 3console.log(response.status);4console.log(response.headers.get("location"));5console.log(response.redirected);

A redirect is a reply that says "look at this other URL instead". Line 1 builds a 302 redirect response with Response.redirect. Line 3 prints 302. Line 4 prints the location header, which holds the new URL. Line 5 prints false. redirected is true only when fetch really followed a redirect. This response was built by hand, so it is false.

bodyUsed tells you whether the body has been read. It starts as false. It becomes true as soon as something starts reading the body. A reader reads a body in pieces, called chunks. That lets a page handle a large reply one piece at a time.

1(async () => {2const response = new Response("hello");3const reader = response.body.getReader();4 5console.log(response.bodyUsed);6const first = await reader.read();7console.log(new TextDecoder().decode(first.value), first.done);8console.log(response.bodyUsed);9console.log((await reader.read()).done);10})();

• Line 2 makes a response with the body "hello". No network is used.
• Line 3 gets a reader for the body.
• Line 5 prints false: nothing has been read yet.
• Line 6 reads the first chunk. Line 7 turns its bytes back into text with TextDecoder and prints hello false. Here false means the stream isn't finished yet.
• Line 8 prints true, because reading has started.
• Line 9 reads again and prints true: the stream is finished.

1(async () => {2const response = new Response(JSON.stringify({ name: "Asha" }));3const copy = response.clone();4 5console.log((await response.json()).name);6console.log((await copy.json()).name);7})();

Line 3 makes the copy before anything reads the body. Line 5 reads the original and prints Asha. Line 6 reads the copy and also prints Asha. Each one had its own body. Only clone when two parts of your code really need the body: the browser may have to keep a second copy of the data in memory.

1const request = new Request("https://example.test/profile", {2  method: "POST",3  mode: "cors",4  credentials: "include",5  cache: "no-store",6  redirect: "manual",7  keepalive: true,8  body: "name=Asha",9});10 11console.log(request.mode, request.credentials);12console.log(request.cache, request.redirect, request.keepalive);

Three of these options are new:

• mode says which rules apply to requests to other websites. "cors" allows a request to another website only if that website agrees.
• redirect says what to do with a redirect: follow it, fail, or hand it to your code.
• keepalive lets a small request finish even while the page is closing.

Line 11 prints cors include. Line 12 prints no-store manual true. The Request keeps every choice. But these options don't give your code extra powers: the browser and the server still apply their own rules.

Response.json(data, init) builds a response with a JSON body. It also sets the Content-Type header for you. Browsers added it in 2023, so the lab checks that it exists before using it. For older browsers, use new Response(JSON.stringify(data), ...) instead.

Credentials are login details the browser keeps for you: cookies, HTTP logins, and client certificates. The credentials option says whether they may go with the request.

An origin is the start of a URL: its scheme, domain, and port, such as https://example.com. A request to the page's own origin is same-origin. A request to any other origin is cross-origin.

The default is "same-origin": credentials go only to the page's own origin. To send them cross-origin, you need "include", and the other server must allow it with CORS headers. CORS is the topic of the next lesson.

The table below lists the three values. Read each row as: with this value, this is what the browser sends.

1for (const credentials of ["omit", "same-origin", "include"]) {2  const request = new Request("https://example.test/profile", { credentials });3  console.log(credentials, request.credentials);4}

The loop makes one Request per value. It prints each value twice: once from the list, and once from the request. They match, because the Request keeps what you chose. Use omit for public data. Use the default, same-origin, for normal requests to your own site. Use include only to send credentials to another origin that allows it.

The browser's HTTP cache is a store of earlier replies. When a saved reply is still good, the browser can use it instead of asking the server again. The cache option tells the browser how to use that store for one request. It doesn't make the server any faster.

Read each row of the next table as: with this value, this is how the browser uses its cache.

1const request = new Request("https://example.test/stats", {2  cache: "no-store",3});4 5console.log(request.cache);

Line 1 builds a request for a stats URL. Line 2 picks no-store. Line 5 prints no-store. With this value, the browser doesn't look in its cache, and it doesn't save the reply there. It still needs the server, so this is not an offline mode.

Three more options, for quick reference. Read each row as: this option answers this question.

1await fetch(location.href, { cache: "default" });2await fetch(location.href, { cache: "no-store" });3 4await fetch("/api/profile", { credentials: "omit" });5await fetch("/api/profile", { credentials: "same-origin" });6await fetch("/api/profile", { credentials: "include" });

redirect: "follow" is the default: fetch follows a redirect to the new URL. "error" makes fetch fail on a redirect. "manual" hands the redirect response to your code. keepalive: true is for small requests sent while the page closes, such as "the user left the page". It is not for big uploads.

The lab sends two HEAD requests to this page. HEAD asks for the headers only, without the body. One request uses cache: "default", and one uses cache: "no-store". On a page like this one, the status and headers often look the same. That is expected: a cache value is only an instruction to the browser. To see a difference, you usually need cache headers from the server, or the browser's developer tools.

You'll use these parts in every app that saves data: todo lists, dashboards, profile pages, checkouts, admin tools, and search pages. Each time, you pick a method, add headers, turn the body into text, check the status, and read the body once.

• Loading a dashboard: GET /api/stats. Add cache: "no-store" if the numbers must be fresh.
• Creating a todo: POST /api/todos with a JSON body. The reply has a Location header.
• Saving a whole profile form: PUT /api/profile, because the form replaces the whole saved profile.
• Ticking one checkbox: PATCH /api/todos/2 with only { completed: true }.
• Stopping a slow request: add an AbortController signal to the same options.

• "POST always creates something." POST usually sends data to a list or an action. But the server decides what each URL does.
• "Idempotent means the reply is always the same." No. It means the data on the server ends up the same. The status can change: a second DELETE may get 404, because the todo is already gone.
• "Header names care about upper and lower case." They don't. headers.get("content-type") finds Content-Type.
• "I should set Content-Type for every body." Set it for JSON. Don't set it for FormData; the browser does that.
• "I can read a request body as often as I like." A body is a stream, and it can be read once. Clone first if you need two reads.
• "credentials: include gets around CORS." It doesn't. To send credentials to another origin, that server must allow it with CORS headers.

The table below lists request parts that are easy to mix up. Read each row as: this part answers this question.

Key takeaways

• A method says what you want: GET reads, POST sends something new, PUT replaces, PATCH changes one part, and DELETE removes.
• GET, HEAD, and OPTIONS are safe: they only read. GET, HEAD, OPTIONS, PUT, and DELETE are idempotent: repeating them leaves the same result.
• Header names ignore case. set replaces a header's values; append adds one more value.
• To send JSON, use a method that can carry a body, set Content-Type: application/json, and use JSON.stringify.
• A request or response body can be read only once. Call clone() before reading it twice.
• credentials is same-origin by default. The cache option tells the browser how to use its saved replies.

Final definition: A full fetch request has a method, a URL, headers, a body, and credentials and cache settings. The answer is a Response. Its status, headers, and read-once body tell you what the server said.

Up next: CORS & cross-origin requests.