Fetch API

So far, we know quite a bit about fetch.

Let’s see the rest of API, to cover all its abilities.

Here’s the full list of all possible fetch options with their default values (alternatives in comments):

let promise = fetch(url, {
  method: "GET", // POST, PUT, DELETE, etc.
  headers: {
    // the content type header value is usually auto-set
    // depending on the request body
    "Content-Type": "text/plain;charset=UTF-8"
  },
  body: undefined // string, FormData, Blob, BufferSource, or URLSearchParams
  referrer: "about:client", // or "" to send no Referer header,
  // or an url from the current origin
  referrerPolicy: "no-referrer-when-downgrade", // no-referrer, origin, same-origin...
  mode: "cors", // same-origin, no-cors
  credentials: "same-origin", // omit, include
  cache: "default", // no-store, reload, no-cache, force-cache, or only-if-cached
  redirect: "follow", // manual, error
  integrity: "", // a hash, like "sha256-abcdef1234567890"
  keepalive: false, // true
  signal: undefined, // AbortController to abort request
  window: window // null
});

An impressive list, right?

We fully covered method, headers and body in the chapter fetch.

The signal option is covered in Fetch: Abort.

Now let’s explore the rest of capabilities.

referrer, referrerPolicy

These options govern how fetch sets HTTP Referer header.

Usually that header is set automatically and contains the url of the page that made the request. In most scenarios, it’s not important at all, sometimes, for security purposes, it makes sense to remove or shorten it.

The referrer option allows to set any Referer within the current origin) or remove it.

To send no referer, set an empty string:

fetch('/page', {
  referrer: "" // no Referer header
});

To set another url within the current origin:

fetch('/page', {
  // assuming we're on https://javascript.info
  // we can set any Referer header, but only within the current origin
  referrer: "https://javascript.info/anotherpage"
});

The referrerPolicy option sets general rules for Referer.

Requests are split into 3 types:

1. Request to the same origin.
2. Request to another origin.
3. Request from HTTPS to HTTP (from safe to unsafe protocol).

Unlike referrer option that allows to set the exact Referer value, referrerPolicy tells the browser general rules for each request type.

Possible values are described in the Referrer Policy specification:

• "no-referrer-when-downgrade" – the default value: full Referer is sent always, unless we send a request from HTTPS to HTTP (to less secure protocol).
• "no-referrer" – never send Referer.
• "origin" – only send the origin in Referer, not the full page URL, e.g. only http://site.com instead of http://site.com/path.
• "origin-when-cross-origin" – send full Referer to the same origin, but only the origin part for cross-origin requests (as above).
• "same-origin" – send full Referer to the same origin, but no Referer for cross-origin requests.
• "strict-origin" – send only origin, don’t send Referer for HTTPS→HTTP requests.
• "strict-origin-when-cross-origin" – for same-origin send full Referer, for cross-origin send only origin, unless it’s HTTPS→HTTP request, then send nothing.
• "unsafe-url" – always send full url in Referer, even for HTTPS→HTTP requests.

Here’s a table with all combinations:

Let’s say we have an admin zone with URL structure that shouldn’t be known from outside of the site.

If we send a fetch, then by default it always sends the Referer header with the full url of our page (except when we request from HTTPS to HTTP, then no Referer).

E.g. Referer: https://javascript.info/admin/secret/paths.

If we’d like other websites know only the origin part, not URL-path, we can set the option:

fetch('https://another.com/page', {
  // ...
  referrerPolicy: "origin-when-cross-origin" // Referer: https://javascript.info
});

We can put it to all fetch calls, maybe integrate into JavaScript library of our project that does all requests and uses fetch inside.

Its only difference compared to the default behavior is that for requests to another origin fetch sends only the origin part of the URL (e.g. https://javascript.info, without path). For requests to our origin we still get the full Referer (maybe useful for debugging purposes).

mode

The mode option is a safe-guard that prevents occasional cross-origin requests:

• "cors" – the default, cross-origin requests are allowed, as described in CORS,
• "same-origin" – cross-origin requests are forbidden,
• "no-cors" – only simple cross-origin requests are allowed.

This option may be useful when the URL for fetch comes from a 3rd-party, and we want a “power off switch” to limit cross-origin capabilities.

credentials

The credentials option specifies whether fetch should send cookies and HTTP-Authorization headers with the request.

• "same-origin" – the default, don’t send for cross-origin requests,
• "include" – always send, requires Accept-Control-Allow-Credentials from cross-origin server in order for JavaScript to access the response, that was covered in the chapter CORS,
• "omit" – never send, even for same-origin requests.

cache

By default, fetch requests make use of standard HTTP-caching. That is, it honors Expires, Cache-Control headers, sends If-Modified-Since, and so on. Just like regular HTTP-requests do.

The cache options allows to ignore HTTP-cache or fine-tune its usage:

• "default" – fetch uses standard HTTP-cache rules and headers,
• "no-store" – totally ignore HTTP-cache, this mode becomes the default if we set a header If-Modified-Since, If-None-Match, If-Unmodified-Since