update fetch guide

[wbamberg]

This is a rewrite of the "Using Fetch" guide": https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch.

The main impetus here was to have a place to talk about bodies being streams, so we can document the exceptions that get thrown when a body is "locked or disturbed" (#13208 (comment)). But unfortunately the structure of this document didn't lend itself to just adding something about that, so I have restructured and rewritten it pretty much completely.

The old doc reads like a collection of facts about fetch in no particular order. In this doc I have three main parts:

• making a request, which has subtopics on the main options you can set
• cancelling a request
• handling a response, which includes checking status and reading/streaming responses

I have thrown out various things:

• "uploading a file" which I think properly belongs in the FormData docs (https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects#sending_files_using_a_formdata_object , but perhaps we should have better linking to that?)
• some stuff comparing with jQuery.ajax, which I think we can dispense with now
• feature-detection stuff, likewise

Other than that I've tried to keep anything in there that seemed useful, although I've reorganized it a lot.

As well as content about streaming responses, I have added quite a bit on cross-origin requests.

I have not described all the options. Specifically I've not described the following:

• attributionReporting
• browsingTopics
• cache
• integrity
• keepalive
• priority
• redirect
• referrer
• referrerPolicy

I feel like describing all of them would make this doc a real slog to read, so I tried describing "the main ones" but that's quite subjective.

---

I'd love feedback about whether this is a generally good "shape" of doc to have here and whether the scope is OK.

Also I this this doc needs careful review by people with really good Fetch knowledge, since some of it is tricky, and I don't know it very well.

In doing this I realize there's definite scope for more Fetch guides, like maybe separate ones of redirects, streaming, CORS, "using fetch securely", ... but I've not attempted that here. I'd welcome feedback on whether I should attempt that in this PR, especially given some of the issues in #34278 (comment)...

• Fix Issue with "Using Fetch": (makeTextFileLineIterator ignores UTF8 multi-byte boundaries) #10086
• Fix Using fetch: explain more about what body/header does #24043
• Fix Issue with "Using Fetch": Add information about SameSite for cookies, when using credentials: 'include' #7025

[github-actions]

Preview URLs

• /en-US/docs/Web/API/Fetch_API/Using_Fetch
• /en-US/docs/Web/API/Fetch_API

(comment last updated: 2024-06-28 14:52:55)

[Josh-Cena]

Here are all issues concerning this page:

• Fetch Basic Sample Code 404 #31841
• Using fetch: split into basic examples and specific use cases #24982
• Using fetch: explain more about what body/header does #24043
• The Example for Form URL Encode and JSON is lost for request. New JS programmer that want to see the example can't find one #14858
• Issue with "Using Fetch": (makeTextFileLineIterator ignores UTF8 multi-byte boundaries) #10086
• Issue with "Using Fetch": Add information about SameSite for cookies, when using credentials: 'include' #7025

Maybe check if this PR happens to fix any of them, or if they are easy enough to be addressed in this PR, or if they aren't really worth fixing?

[wbamberg]

47767e7 adds a bit of explanation about what headers and bodies are, in an attempt to fix #24043.

[wbamberg]

404963d notes that same-site cookies will not be sent cross-site, whatever the value of credentials, in an attempt to fix #7025.

[wbamberg]

Thanks for this!

• Fetch Basic Sample Code 404 #31841

As discussed in that issue, I'm open to this but there are some wrinkles and questions, so not sure if we want to do it now.

• Using fetch: Mixing await/async and .then/.finally syntax #24982

The main bit of this is addressed. The rest seems to be about potentially splitting this guide into "basic fetch" and separate guides for more detailed things. Again I can see the value of that and if that's the way people want to go with this PR I'm happy to. But we'd need to think of what the other things would be. Maybe:

• cross-origin requests (including CORS, credentials, CSP)
• POST requests
• redirects?
• streaming responses (but even so I think we need to talk about "disturbed" and "locked" in the basic guide, since it affects basic usage as well)

• Using fetch: explain more about what body/header does #24043

Added 47767e7 in this PR which should address that.

• The Example for Form URL Encode and JSON is lost for request. New JS programmer that want to see the example can't find one #14858

I wonder if this indicates that we should have a separate "Making POST requests" guide, to provide a home for this and for the "upload a file" and upload forms" examples.

• Issue with "Using Fetch": (makeTextFileLineIterator ignores UTF8 multi-byte boundaries) #10086

I'm not at all familiar with the streams API but:

• this is already quite a complicated example in which a lot of the complexity comes out of text handling, rather than fetch. So it's not a great example of response streaming per se, and I'd be reluctant to make it more complicated (rather than change the example to a simpler use case).
• it seems weird that we have to build our own UTF8 on top of TextDecoder, which is....a UTF8 decoder. Can we use TextDecoderStream here? Like some version of:

  fetch(`/receive?channel=${channel}`).then(async res => {
    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) return;
      output.append(value);
    }
  });

...from https://glitch.com/edit/#!/fetch-request-stream?path=static%2Fmain.js%3A50%3A0 ?

• Issue with "Using Fetch": Add information about SameSite for cookies, when using credentials: 'include' #7025

Added 404963d in this PR which should address that.

[Josh-Cena]

Great, so in conclusion this PR (aims to) fix #24043 and #7025?

[wbamberg]

Great, so in conclusion this PR (aims to) fix #24043 and #7025?

At least those two :).

[Josh-Cena]

Looks great!

[wbamberg]

• Issue with "Using Fetch": (makeTextFileLineIterator ignores UTF8 multi-byte boundaries) #10086

I'm not at all familiar with the streams API but:

• this is already quite a complicated example in which a lot of the complexity comes out of text handling, rather than fetch. So it's not a great example of response streaming per se, and I'd be reluctant to make it more complicated (rather than change the example to a simpler use case).

• it seems weird that we have to build our own UTF8 on top of TextDecoder, which is....a UTF8 decoder. Can we use TextDecoderStream here? Like some version of:

  fetch(`/receive?channel=${channel}`).then(async res => {
    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) return;
      output.append(value);
    }
  });

...from https://glitch.com/edit/#!/fetch-request-stream?path=static%2Fmain.js%3A50%3A0 ?

So for instance, can we have a streaming example like this:

const url = "https://www.gutenberg.org/cache/epub/34225/pg34225.txt";

async function fetchAsStream(url) {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Response status: ${response.status}`);
    }

    const reader = response.body.pipeThrough(new TextDecoderStream());
    for await (const value of reader) {
      console.log(value);
    }
  } catch (e) {
    console.error(e);
  }
}

I've tried this in Chrome with network throttling, and it works nicely to deliver chunks of text as they come in (compared with the await response.text() version, which takes ages to fulfill). Would be nice to have a large text file that works cross-origin, which gutenberg doesn't.

I think this is a lot clearer than the "read line by line" example, and shows the point of streaming responses quite clearly. WDYT?

[Josh-Cena]

I think this is a lot clearer than the "read line by line" example, and shows the point of streaming responses quite clearly. WDYT?

That looks great to me 👍

Great, so in conclusion this PR (aims to) fix #24043 and #7025?

At least those two :).

I've linked them to this PR

[wbamberg]

This commit: fbf188b adds the simpler streaming example, and also fixes #10086 by piping the response body through a UTF-8 decoder.

I've confirmed (using https://www.gutenberg.org/cache/epub/30774/pg30774.txt) that:

• the old code did mess up multibyte UTF-8 encodings when they happened at chunk boundaries
• the new code doesn't

[wbamberg]

In c441596 I deleted https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Basic_concepts, because it only talked about "guard", which is an internal spec concept, and whose effect is, with this PR, now documented in the main "using fetch" guide.

[Josh-Cena]

Leaving a verbal approval; if you don't get it merged in a week we can merge it

[Josh-Cena]

(@sideshowbarker bumping this up your inbox)

[sideshowbarker]

Looks great to me — the technical content of the prose and examples. Only found a couple minor proofreading fixes.

[wbamberg]

Thank you for the reviews!

[wesinator]

I liked the example https://web.archive.org/web/20240612035627/https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options because it was a complete structure, and the other examples in the old page had examples for specific use cases where one could learn from the examples, not simply atomic pieces of the Fetch API. (I used this old example recently and found it helpful, then I noticed this documentation change).

Would it be possible to add the Supplying Request Options example back?

[wbamberg]

Of course, but I'd like to understand better what you mean by "a complete structure". The example at the start of the new page is also "complete" in that it runs, as is the "making a POST request" example and most of the other examples in the page. On the other hand https://web.archive.org/web/20240612035627/https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options is not complete in the sense of showing all the options, it only shows some of them, and I'm not sure what's the basis for the choices it makes about which ones to show.

Perhaps we could update the example to show all the options?

I also think the old example is odd in that it passes options which are the same as the default, which makes me think why would someone do that.

[Josh-Cena]

-1 to add it back, or to have any example that has every option configured. If you want to read up on all possible options, read the reference instead of the guide, which shows you how to use the API. You don't use the API by configuring every option; you change what you need.