Integrate fetchLater() API into Fetch (mdn#42693)

* Move fetchlater API docs into fetch API

* Fix a typo

* Merge fetchLater groupdata into fetch

* Fix sidebars

* Delete and redirect fetchlater API pages; update links

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Add more links

* Reword fetchLater description

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: wbamberg

files/en-us/_redirects.txt

@@ -11224,6 +11224,8 @@
 /en-US/docs/Web/API/event.view	/en-US/docs/Web/API/UIEvent/view
 /en-US/docs/Web/API/event.which	/en-US/docs/Web/API/UIEvent/which
 /en-US/docs/Web/API/fetch	/en-US/docs/Web/API/Window/fetch
+/en-US/docs/Web/API/fetchLater_API	/en-US/docs/Web/API/Fetch_API
+/en-US/docs/Web/API/fetchLater_API/fetchLater_quotas	/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch
 /en-US/docs/Web/API/form.acceptCharset	/en-US/docs/Web/API/HTMLFormElement/acceptCharset
 /en-US/docs/Web/API/form.action	/en-US/docs/Web/API/HTMLFormElement/action
 /en-US/docs/Web/API/form.elements	/en-US/docs/Web/API/HTMLFormElement/elements

files/en-us/web/api/deferredrequestinit/index.md

@@ -7,9 +7,9 @@ status:
 browser-compat: api.Window.fetchLater
 ---
 
-{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}}
+{{DefaultAPISidebar("Fetch API")}}{{SeeCompatTable}}
 
-The **`DeferredRequestInit`** dictionary of the [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) represents the set of options that can be used to configure a deferred fetch request.
+The **`DeferredRequestInit`** dictionary of the [Fetch API](/en-US/docs/Web/API/Fetch_API) represents the set of options that can be used to configure a deferred fetch request.
 
 The `DeferredRequestInit` object is passed directly into the {{domxref("window.fetchLater()")}} function call as the second argument.
 
@@ -60,7 +60,7 @@ fetchLater("/send_beacon", {
 
 ## See also
 
-- [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch)
+- [Using Deferred Fetch](/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch)
 - [ServiceWorker API](/en-US/docs/Web/API/Service_Worker_API)
 - [HTTP access control (CORS)](/en-US/docs/Web/HTTP/Guides/CORS)
 - [HTTP](/en-US/docs/Web/HTTP)

files/en-us/web/api/fetch_api/index.md

@@ -2,10 +2,12 @@
 title: Fetch API
 slug: Web/API/Fetch_API
 page-type: web-api-overview
-browser-compat: api.fetch
+browser-compat:
+  - api.fetch
+  - api.Window.fetchLater
 ---
 
-{{DefaultAPISidebar("Fetch API")}} {{AvailableInWorkers}}
+{{DefaultAPISidebar("Fetch API")}}
 
 The Fetch API provides an interface for fetching resources (including across the network). It is a more powerful and flexible replacement for {{DOMxRef("XMLHttpRequest")}}.
 
@@ -23,17 +25,34 @@ You can create a request and response directly using the {{DOMxRef("Request.Requ
 
 Find out more about using the Fetch API features in [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch).
 
+### Deferred Fetch
+
+The {{domxref("Window/fetchLater", "fetchLater()")}} API enables a developer to request a _deferred fetch_, that can be sent after a specified period of time, or when the page is closed or navigated away from. See [Using Deferred Fetch](/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch).
+
 ## Interfaces
 
 - {{domxref("Window.fetch()")}} and {{domxref("WorkerGlobalScope.fetch()")}}
   - : The `fetch()` method used to fetch a resource.
+- {{domxref("Window.fetchLater()")}}
+  - : Used to make a deferred fetch request.
+- {{domxref("DeferredRequestInit")}}
+  - : Represents the set of options that can be used to configure a deferred fetch request.
+- {{domxref("FetchLaterResult")}}
+  - : Represents the result of requesting a deferred fetch.
 - {{DOMxRef("Headers")}}
   - : Represents response/request headers, allowing you to query them and take different actions depending on the results.
 - {{DOMxRef("Request")}}
   - : Represents a resource request.
 - {{DOMxRef("Response")}}
   - : Represents the response to a request.
 
+## HTTP headers
+
+- {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}}
+  - : Controls the [top-level quota](/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch#quotas) for the `fetchLater()` API.
+- {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}}
+  - : Controls the [shared cross-origin subframe quota](/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch#quotas) for the `fetchLater()` API.
+
 ## Specifications
 
 {{Specifications}}

…etchlater_api/fetchlater_quotas/index.md …/fetch_api/using_deferred_fetch/index.mdfiles/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md renamed to files/en-us/web/api/fetch_api/using_deferred_fetch/index.md files/en-us/web/api/fetchlater_api/fetchlater_quotas/index.md renamed to files/en-us/web/api/fetch_api/using_deferred_fetch/index.md

@@ -1,22 +1,45 @@
 ---
-title: fetchLater() quotas
-slug: Web/API/fetchLater_API/fetchLater_quotas
+title: Using Deferred Fetch
+slug: Web/API/Fetch_API/Using_Deferred_Fetch
 page-type: guide
-status:
-  - experimental
-browser-compat:
-  - http.headers.Permissions-Policy.deferred-fetch
-  - http.headers.Permissions-Policy.deferred-fetch-minimal
 ---
 
-{{DefaultAPISidebar("fetchLater API")}}{{SeeCompatTable}}
+{{DefaultAPISidebar("Fetch API")}}
 
-Deferred [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) fetches are batched and sent once the tab is closed. At this point, there is no way for the user to abort them. To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network the API sets quotas on how much data can be deferred to be sent later.
-
-These quotas can be managed through {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} and {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives.
+The **`fetchLater()` API** provides an interface to request a deferred fetch that can be sent after a specified period of time, or when the page is closed or navigated away from.
 
 ## Overview
 
+Developers often need to send (or beacon) data back to the server, particularly at the end of a user's visit to a page — for example, for analytics services. There are several ways to do this: from adding 1 pixel {{HTMLElement("img")}} elements to the page, to {{domxref("XMLHttpRequest")}}, to the dedicated {{domxref("Beacon API", "Beacon API", "", "nocode")}}, and the {{domxref("Fetch API", "Fetch API", "", "nocode")}} itself.
+
+The issue is that all of these methods suffer from reliability problems for end-of-visit beaconing. While the Beacon API and the {{domxref("Request.keepalive", "keepalive")}} property of the Fetch API will send data, even if the document is destroyed (to the best efforts that can be made in this scenario), this only solves part of the problem.
+
+The other — more difficult — part to solve concerns deciding _when_ to send the data, since there is not an ideal time in a page's lifecycle to make the JavaScript call to send out the beacon:
+
+- The {{domxref("Window.unload_event", "unload")}} and {{domxref("Window.beforeunload_event", "beforeunload")}} events are unreliable, and outright ignored by several major browsers.
+- The {{domxref("Window.pagehide_event", "pagehide")}} and {{domxref("document.visibilitychange_event", "visibilitychange")}} events are more reliable, but still have issues on mobile platforms.
+
+This means developers looking to reliably send out data via a beacon need to do so more frequently than is ideal. For example, they may send a beacon on each change, even if the final value for the page has not yet been reached. This has costs in network usage, server processing, and merging or discarding outdated beacons on the server.
+
+Alternatively, developers can choose to accept some level of missing data — either by:
+
+- Beaconing after a designated cut-off time and not collecting later data.
+- Beaconing at the end of the page lifecycle but accepting that sometimes this will not be reliable.
+
+The `fetchLater()` API extends the {{domxref("Fetch API", "Fetch API", "", "nocode")}} to allow setting fetch requests up in advance. These deferred fetches can be updated before they have been sent, allowing the payload to reflect the latest data to be beaconed.
+
+The browser then sends the beacon when the tab is closed or navigated away from, or after a set time if specified. This avoids sending multiple beacons but still ensures a reliable beacon within reasonable expectations (i.e., excluding when the browser process shuts down unexpectedly during a crash).
+
+Deferred fetches can also be aborted using an {{domxref("AbortController")}} if they are no longer required, avoiding further unnecessary costs.
+
+## Quotas
+
+Deferred fetches are batched and sent once the tab is closed; at this point, there is no way for the user to abort them. To avoid situations where documents abuse this bandwidth to send unlimited amounts of data over the network, the overall quota for a top-level document is capped at 640KiB.
+
+Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they embed third-party JavaScript.
+
+Since this cap makes deferred fetch bandwidth a scarce resource, which needs to be shared between multiple reporting origins (for example, several RUM libraries) and subframes from multiple origins, the platform provides a reasonable default division of this quota. In addition, it provides {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} and {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) directives to allow dividing it differently when desired.
+
 The overall quota for `fetchLater()` is 640KiB per document. By default, this is divided into a 512KiB top-level quota and a 128KiB shared quota:
 
 - The 512KiB top-level quota by default is for any `fetchLater()` requests made from the top-level document and direct subframes using that origin.
@@ -26,33 +49,33 @@ The overall quota for `fetchLater()` is 640KiB per document. By default, this is
 
 For example, if a top-level `a.com` document includes a `<script>` that makes a `fetchLater()` request to `analytics.example.com`, this request would be bound by the top-level 512KiB limit. Alternatively, if the top-level document embeds an `<iframe>` with a source of `analytics.example.com` that makes a `fetchLater()` request, that request would be bound by the 128KiB limit.
 
-## Quota limits by reporting origin and subframe
+### Quota limits by reporting origin and subframe
 
 Only 64KiB of the top-level 512KiB quota can be used concurrently for the same reporting origin (the request URL's origin). This prevents third-party libraries from reserving quota opportunistically before they have data to send.
 
 Each cross-origin subframe gets an 8KiB quota out of the shared 128KiB quota by default, allocated when the subframe is added to the DOM (whether `fetchLater()` will be used in that subframe or not). This means that, in general, only the first 16 cross-origin subframes added to a page can use `fetchLater()` as they will use up the 128KiB quota.
 
-## Increasing subframe quotas by sharing the top-level quota
+### Increasing subframe quotas by sharing the top-level quota
 
 The top-level origin can give selected cross-origin subframes an increased quota of 64KiB, taking it out of the larger top-level 512KiB limit. It does this by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch", "deferred-fetch")}} Permissions Policy directive. This is allocated when the subframe is added to the DOM, leaving less quota for the top-level document and direct same-origin subframes. Multiple same-origin subdomains can each get a 64KiB quota.
 
-## Restricting the shared quota
+### Restricting the shared quota
 
 The top-level origin can also restrict the 128KiB shared quota to named cross-origin subframes by listing those origins in the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy. It can also revoke the entire 128KiB default subframe quota and instead keep the full 640KiB quota for itself and any named `deferred-fetch` cross-origins by setting the {{HTTPHeader("Permissions-Policy/deferred-fetch-minimal", "deferred-fetch-minimal")}} Permissions Policy to `()`.
 
-## Delegating quotes to subframes of subframes
+### Delegating quotes to subframes of subframes
 
 By default, subframes of subframes are not allocated a quota and so cannot use `fetchLater()`. Subframes allocated the increased 64KiB quota can delegate the full 64KiB quota to further subframes and allow them to use `fetchLater()` by setting their own `deferred-fetch` Permissions Policy. They can only delegate their full quota to further subframes, not parts of it, and cannot specify new quotas. Subframes using the minimal 8KiB quota cannot delegate quotas to subframes. To be delegated quota, sub-subframes must be included in both the top-level and the subframe `deferred-fetch` {{httpheader('Permissions-Policy')}} directives.
 
-## When quotas are exceeded
+### When quotas are exceeded
 
 When quotas are exceeded, a `QuotaExceededError` is thrown when the {{domxref('Window.fetchLater()','fetchLater()')}} method is called to initiate the deferred request.
 
 Permissions Policy checks are not discernible from quota checks. Calling `fetchLater()` will throw a `QuotaExceededError` both if the quota is actually exceeded and if the quota was restricted for that origin via a Permissions Policy.
 
 Callers of `fetchLater()` should be defensive and catch `QuotaExceededError` errors in almost all cases, especially if they embed third-party JavaScript.
 
-## Examples
+## Quota examples
 
 ### Using up the minimal quota
 
@@ -212,15 +235,3 @@ Assuming a top-level document at `a.com`, which embeds `<iframe src="https://b.c
 1. The top-level frame of `a.com` has the default 512KiB quota.
 2. `<iframe src="https://b.com/">` receives 8KiB of the default shared quota of 128KiB.
 3. The 8KiB is not transferred to `a.com` when `<iframe src="https://b.com/">` redirects there, but it can share the full top-level quota again, and the previously-allocated 8KiB quota is released.
-
-## Specifications
-
-{{Specifications}}
-
-## Browser compatibility
-
-{{Compat}}
-
-## See also
-
-- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API)

files/en-us/web/api/fetchlater_api/index.md

@@ -7,9 +7,9 @@ status:
 browser-compat: api.FetchLaterResult
 ---
 
-{{APIRef("fetchLater API")}}{{SeeCompatTable}}
+{{APIRef("Fetch API")}}{{SeeCompatTable}}
 
-The **`FetchLaterResult`** interface of the [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API) is returned by the {{domxref("Window.fetchLater()")}} method after a deferred fetch has been created.
+The **`FetchLaterResult`** interface of the [Fetch API](/en-US/docs/Web/API/Fetch_API) is returned by the {{domxref("Window.fetchLater()")}} method after a deferred fetch has been created.
 
 It contains a single `activated` property that indicates whether the deferred request has been sent out or not.
 
@@ -46,5 +46,5 @@ function checkIfFetched() {
 
 ## See also
 
-- [`fetchLater()` API](/en-US/docs/Web/API/fetchLater_API)
 - [Fetch API](/en-US/docs/Web/API/Fetch_API)
+- [Using Deferred Fetch](/en-US/docs/Web/API/Fetch_API/Using_Deferred_Fetch)