Document request options in one place (#34437)

Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: sideshowbarker <[email protected]>
mdn · Jul 2, 2024 · 413ce1e · 413ce1e
1 parent b03b097
commit 413ce1e
Show file tree

Hide file tree

Showing 5 changed files with 302 additions and 169 deletions.
diff --git a/files/en-us/web/api/fetch/index.md b/files/en-us/web/api/fetch/index.md
@@ -38,106 +38,7 @@ fetch(resource, options)
 
 - `options` {{optional_inline}}
 
-  - : An object containing any custom settings you want to apply to the request.
-    The possible options are:
-
-    - `attributionReporting` {{experimental_inline}}
-
-      - : Indicates that you want the request's response to be able to register a JavaScript-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#javascript-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#javascript-based_attribution_triggers). `attributionReporting` is an object containing the following properties:
-
-        - `eventSourceEligible`
-          - : A boolean. If set to `true`, the request's response is eligible to register an attribution source. If set to `false`, it isn't.
-        - `triggerEligible`
-          - : A boolean. If set to `true`, the request's response is eligible to register an attribution trigger. If set to `false`, it isn't.
-
-        > **Note:** See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) for more details.
-
-    - `body`
-
-      - : Any body that you want to add to your request:
-        this can be a {{domxref("Blob")}}, an {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}},
-        a {{domxref("FormData")}}, a {{domxref("URLSearchParams")}}, string object or literal,
-        or a {{domxref("ReadableStream")}} object. This latest possibility is still experimental; check the [compatibility information](/en-US/docs/Web/API/Request#browser_compatibility) to verify you can use it.
-        Note that a request using the `GET` or `HEAD` method cannot have a body.
-
-    - `browsingTopics` {{experimental_inline}}
-
-      - : A boolean specifying that the selected topics for the current user should be sent in a {{httpheader("Sec-Browsing-Topics")}} header with the associated request. See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
-
-    - `cache`
-
-      - : A string indicating how the request will interact with the browser's [HTTP cache](/en-US/docs/Web/HTTP/Caching). The possible values, `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`, are documented in the article for the {{domxref("Request/cache", "cache")}} property of the {{domxref("Request")}} object.
-
-    - `credentials`
-
-      - : Controls what browsers do with credentials ([cookies](/en-US/docs/Web/HTTP/Cookies), [HTTP authentication](/en-US/docs/Web/HTTP/Authentication) entries, and TLS client certificates). Must be one of the following strings:
-
-        - `omit`: Tells browsers to exclude credentials from the request, and ignore any credentials sent back in the response (e.g., any {{HTTPHeader("Set-Cookie")}} header).
-        - `same-origin`: Tells browsers to include credentials with requests to same-origin URLs, and use any credentials sent back in responses from same-origin URLs. **This is the default value.**
-        - `include`: Tells browsers to include credentials in both same- and cross-origin requests, and always use any credentials sent back in responses.
-
-          > **Note:** Credentials may be included in simple and "final" cross-origin requests, but should not be included in [CORS preflight requests](/en-US/docs/Web/HTTP/CORS#preflight_requests_and_credentials).
-
-    - `headers`
-
-      - : Any headers you want to add to your request, contained within a {{domxref("Headers")}} object or an object literal with {{jsxref("String")}} values.
-        Note that [some names are forbidden](/en-US/docs/Glossary/Forbidden_header_name).
-
-        > **Note:** The [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) HTTP header may be added to a request, but will be removed if the request is redirected cross-origin.
-
-    - `integrity`
-
-      - : Contains the [subresource integrity](/en-US/docs/Web/Security/Subresource_Integrity)
-        value of the request (e.g., `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).
-
-    - `keepalive`
-      - : The `keepalive` option can be used to allow the request to outlive the page.
-        Fetch with the `keepalive` flag is a replacement for the {{domxref("Navigator.sendBeacon()")}} API.
-    - `method`
-
-      - : The request method, e.g., `"GET"`, `"POST"`.
-        The default is `"GET"`.
-        Note that the {{httpheader("Origin")}} header is not set on Fetch requests with a method of {{HTTPMethod("HEAD")}} or {{HTTPMethod("GET")}}.
-        Any string which is a case-insensitive match for one of the methods in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-overview) will be uppercased automatically.
-        If you want to use a custom method (like `PATCH`), you should uppercase it yourself.
-
-    - `mode`
-      - : The mode you want to use for the request, e.g., `cors`,
-        `no-cors`, or `same-origin`.
-    - `priority`
-      - : Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:
-        - `high`
-          - : A high priority fetch request relative to other requests of the same type.
-        - `low`
-          - : A low priority fetch request relative to other requests of the same type.
-        - `auto`
-          - : Automatically determine the priority of the fetch request relative to other requests of the same type (default).
-    - `redirect`
-
-      - : How to handle a `redirect` response:
-
-        - `follow`
-          - : Automatically follow redirects. Unless otherwise stated the redirect mode is set to `follow`.
-        - `error`
-          - : Abort with an error if a redirect occurs.
-        - `manual`
-          - : Caller intends to process the response in another context.
-            See [WHATWG fetch standard](https://fetch.spec.whatwg.org/#concept-request-redirect-mode) for more information.
-
-    - `referrer`
-
-      - : A string specifying the referrer of the request. This can be a
-        same-origin URL, `about:client`, or an empty string.
-
-    - `referrerPolicy`
-      - : Specifies the [referrer policy](https://w3c.github.io/webappsec-referrer-policy/#referrer-policies) to use for the request. May be one of `no-referrer`,
-        `no-referrer-when-downgrade`, `same-origin`,
-        `origin`, `strict-origin`,
-        `origin-when-cross-origin`,
-        `strict-origin-when-cross-origin`, or `unsafe-url`.
-    - `signal`
-      - : An {{domxref("AbortSignal")}} object instance; allows you to communicate with a
-        fetch request and abort it if desired via an {{domxref("AbortController")}}.
+  - : A {{domxref("RequestInit")}} object containing any custom settings that you want to apply to the request.
 
 ### Return value
 

diff --git a/files/en-us/web/api/request/credentials/index.md b/files/en-us/web/api/request/credentials/index.md
@@ -8,28 +8,30 @@ browser-compat: api.Request.credentials
 
 {{APIRef("Fetch API")}}
 
-The **`credentials`** read-only property of the {{domxref("Request")}} interface indicates whether the user agent should send or receive cookies from the other domain in the case of cross-origin requests.
+The **`credentials`** read-only property of the {{domxref("Request")}} interface reflects the value given to the {{domxref("Request.Request()", "Request()")}} constructor in the [`credentials`](/en-US/docs/Web/API/RequestInit#credentials) option, and determines whether or not the browser sends credentials with the request.
+
+Credentials are cookies, {{glossary("TLS")}} client certificates, or authentication headers containing a username and password.
+
+See [Including credentials](/en-US/docs/Web/API/Fetch_API/Using_Fetch#including_credentials) for more details.
 
 ## Value
 
-A `RequestCredentials` dictionary value indicating whether the user agent should send or receive cookies from the other domain in the case of cross-origin requests. Possible values are:
+A string with one of the following values:
 
 - `omit`
-  - : Never send or receive cookies.
+  - : Never send credentials in the request or include credentials in the response.
 - `same-origin`
-  - : Send user credentials (cookies, basic http auth, etc..) if the URL is on the same origin as the calling script. **This is the default value.**
+  - : Only send and include credentials for same-origin requests.
 - `include`
-  - : Always send user credentials (cookies, basic http auth, etc..), even for cross-origin calls.
-
-This is similar to XHR's [`withCredentials`](/en-US/docs/Web/API/XMLHttpRequest/withCredentials) flag, but with three available values instead of two.
+  - : Always include credentials, even for cross-origin requests.
 
 ## Examples
 
 In the following snippet, we create a new request using the {{domxref("Request.Request", "Request()")}} constructor (for an image file in the same directory as the script), then save the request credentials in a variable:
 
 ```js
-const myRequest = new Request("flowers.jpg");
-const myCred = myRequest.credentials; // returns "same-origin" by default
+const request = new Request("flowers.jpg");
+const request = request.request; // returns "same-origin" by default
 ```
 
 ## Specifications

diff --git a/files/en-us/web/api/request/request/index.md b/files/en-us/web/api/request/request/index.md
@@ -36,65 +36,7 @@ new Request(input, options)
 
 - `options` {{optional_inline}}
 
-  - : An object containing any custom settings that you want to apply to the
-    request. The possible options are:
-
-    - `attributionReporting` {{experimental_inline}}
-
-      - : Indicates that you want the request's response to be able to register a JavaScript-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#javascript-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#javascript-based_attribution_triggers). `attributionReporting` is an object containing the following properties:
-
-        - `eventSourceEligible`
-          - : A boolean. If set to `true`, the request's response is eligible to register an attribution source. If set to `false`, it isn't.
-        - `triggerEligible`
-          - : A boolean. If set to `true`, the request's response is eligible to register an attribution trigger. If set to `false`, it isn't.
-
-        > **Note:** See the [Attribution Reporting API](/en-US/docs/Web/API/Attribution_Reporting_API) for more details.
-
-    - `body`
-      - : Any body that you want to add to your request: this can be a
-        {{domxref("Blob")}}, an {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}},
-        a {{domxref("FormData")}}, a {{domxref("URLSearchParams")}}, a string, or a {{domxref("ReadableStream")}} object.
-        Note that a request using the `GET` or `HEAD` method cannot have a body.
-    - `browsingTopics` {{experimental_inline}}
-      - : A boolean specifying that the selected topics for the current user should be sent in a {{httpheader("Sec-Browsing-Topics")}} header with the associated request. See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
-    - `cache`
-      - : The [cache mode](/en-US/docs/Web/API/Request/cache) you want to use for the request.
-    - `credentials`
-      - : The request credentials you want to use for the
-        request: `omit`, `same-origin`, or `include`. The
-        default is `same-origin`.
-    - `headers`
-      - : Any headers you want to add to your request, contained
-        within a {{domxref("Headers")}} object or an object literal with
-        {{jsxref("String")}} values.
-    - `integrity`
-      - : Contains the [subresource integrity](/en-US/docs/Web/Security/Subresource_Integrity)
-        value of the request (e.g.,
-        `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).
-    - `keepalive`
-      - : A boolean that indicates whether to make a persistent connection for multiple requests/responses.
-    - `method`
-      - : The request method, e.g., `GET`, `POST`. The default is `GET`.
-    - `mode`
-      - : The mode you want to use for the request, e.g.,
-        `cors`, `no-cors`, `same-origin`, or
-        `navigate`. The default is `cors`.
-    - `priority`
-      - : Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:
-        - `high`: A high priority fetch request relative to other requests of the same type.
-        - `low`: A low priority fetch request relative to other requests of the same type.
-        - `auto`: Automatically determine the priority of the fetch request relative to other requests of the same type (default).
-    - `redirect`
-      - : The redirect mode to use: `follow`,
-        `error`, or `manual`. The default is `follow`.
-    - `referrer`
-      - : A string specifying
-        `no-referrer`, `client`, or a URL. The default is
-        `about:client`.
-    - `referrerPolicy`
-      - : A string that changes how the referrer header is populated during certain actions (e.g., fetching subresources, prefetching, performing navigations).
-    - `signal`
-      - : An [AbortSignal](/en-US/docs/Web/API/AbortSignal) object which can be used to communicate with/abort a request.
+  - : A {{domxref("RequestInit")}} object containing any custom settings that you want to apply to the request.
 
     If you construct a new `Request` from an existing `Request`, any options you set in an _options_ argument for the new request replace any corresponding options set in the original `Request`. For example: