This section documents how requests work in detail. To get started, see +[[#fetch-elsewhere-request]]. +
The input to fetch is a
request.
@@ -1700,7 +1703,7 @@ and "webidentity" as fetches with those destinations skip service w
"xslt" as that too can cause script execution. It is not included in the list as it is
not always relevant and might require different behavior.
-
The following table illustrates the relationship between a request's initiator, destination, CSP directives, and features. It is not exhaustive with respect to features. Features need to have the relevant values defined in their @@ -8438,6 +8441,78 @@ correctly. This section aims to give some advice.
This is a work in progress. +
The first step in fetching is to create a request, and populate its +items. + +
Start by setting the request's URL and method,
+as defined by HTTP. If your `POST` or `PUT` request needs a
+body, you set request's body to a byte sequence, or to
+a new body whose stream is a {{ReadableStream}} you created. [[HTTP]]
+
+
Choose your request's destination using the guidance in the +destination table. Destinations affect +Content Security Policy and have other implications such as the [:Sec-Fetch-Dest:] +header, so they are much more than informative metadata. If a new feature requires a +destination that's not in the destination table, +please +file an issue +to discuss. [[CSP]] + +
Set your request's client to the +environment settings object you're operating in. Web-exposed APIs are generally defined with +Web IDL, for which every object that implements an interface has a +relevant settings object you can use. For example, a request associated with an +element would set the request's client to the element's +node document's relevant settings object. All features that are directly web-exposed +by JavaScript, HTML, CSS, or other {{Document}} subresources should have a +client. + +
If your fetching is not directly web-exposed, e.g., it is sent in the background +without relying on a current {{Window}} or {{Worker}}, leave request's +client as null and set the request's origin, +policy container, service-workers mode, and +referrer to appropriate values instead, e.g., by copying them from the +environment settings object ahead of time. In these more advanced cases, make sure the +details of how your fetch handles Content Security Policy and +referrer policy are fleshed out. Also make sure you handle concurrency, as callbacks +(see [[#fetch-elsewhere-fetch]]) would be posted on a parallel queue. [[REFERRER]] [[CSP]] + +
Think through the way you intend to handle cross-origin resources. Some features may only work in
+the same origin, in which case set your request's mode to
+"same-origin". Otherwise, new web-exposed features should almost always set their
+mode to "cors". If your feature is not web-exposed, or you think
+there is another reason for it to fetch cross-origin resources without CORS, please
+file an issue
+to discuss.
+
+
For cross-origin requests, also determines if credentials are to be included with
+the requests, in which case set your request's credentials mode to
+"include".
+
+
Figure out if your fetch needs to be reported to Resource Timing, and with which +initiator type. By passing an initiator type to the +request, reporting to Resource Timing will be done automatically once the +fetch is done and the response is fully downloaded. [[RESOURCE-TIMING]] + +
If your request requires additional HTTP headers, set its header list to
+a header list that contains those headers, e.g., « (`My-Header-Name`,
+`My-Header-Value`) ». Sending custom headers may have implications, such as requiring a
+CORS-preflight fetch, so handle with care.
+
+
If you want to override the default caching mechanism, e.g., disable caching for this
+request, set the request's cache mode to a value other than
+"default".
+
+
Determine whether you want your request to support redirects. If you don't, set its
+redirect mode to "error".
+
+
Browse through the rest of the parameters for request to see if something else is +relevant to you. The rest of the parameters are used less frequently, often for special purposes, +and they are documented in detail in the [[#requests]] section of this standard. + +
Aside from a request the fetch operation takes several optional