Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document request options in one place #34437

Merged
merged 11 commits into from
Jul 2, 2024
Merged

Document request options in one place #34437

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5406d76
Document request options in one place
wbamberg Jun 26, 2024
55c5368
Update GroupData
wbamberg Jun 26, 2024
b592bef
Update files/en-us/web/api/requestinit/index.md
wbamberg Jun 26, 2024
d827d47
Update files/en-us/web/api/requestinit/index.md
wbamberg Jun 26, 2024
80908bd
Update files/en-us/web/api/requestinit/index.md
wbamberg Jun 26, 2024
a7b70ab
Update files/en-us/web/api/requestinit/index.md
wbamberg Jun 27, 2024
460ca9a
Merge remote-tracking branch 'upstream/main' into requestinit
wbamberg Jun 29, 2024
3acb84d
Add cross-links to guide
wbamberg Jun 29, 2024
a346a00
Merge remote-tracking branch 'origin/requestinit' into requestinit
wbamberg Jun 29, 2024
0f79e72
Fix issue 13063: clean up Request.credentials
wbamberg Jun 29, 2024
8563c90
Apply suggestions from code review
wbamberg Jul 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 1 addition & 100 deletions files/en-us/web/api/fetch/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
60 changes: 1 addition & 59 deletions files/en-us/web/api/request/request/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading