Fetch Request- Scoped, Global
The Fetch Request API contains methods for creating or retrieving a Request object to allow applications to asynchronously request resources, such as JSON, text, or binary data, from a server, and handle the response. This API supports various HTTP methods like GET, POST, PUT, DELETE, and so on.
This API is part of a set of Fetch APIs, which provide various actions for fetching resources from external websites. The full Fetch API collection includes:
- Fetch - fetch(String resource, Object options): Start the process of fetching a resource from the network.
- Fetch Headers - Scoped, Global: Retrieve and modify request and response headers.
- Fetch Request - Scoped, Global: Create a new request object.
- Fetch RequestInit - Scoped, Global: Set options to configure a fetch request.
- Fetch Response - Scoped,Global: Create a new response object.
To support fetch actions, the system property, glide.hosts.allowlist, allows controls over what hosts a fetch method can access. It applies to HTTP APIs like RestMessageV2 and those mentioned above. For more information about glide.hosts.allowlist, see Available system properties.
Request properties
The Fetch Request API supports several read-only properties that offer detailed information about an HTTP request. Some of these include url (the URL of the request), method (the HTTP method), headers (the associated headers), and body (the request body as a stream). Other properties include settings for caching, credentials, and referrers. These properties are read-only, meaning they can be accessed but not modified after the request is created. To read more about each property, see https://developer.mozilla.org/en-US/docs/Web/API/Request.
| Property name | Description | Example |
|---|---|---|
| body | Ready-only property. Contains a readable stream of byte data with the body contents that have been added to the request.Data type/value: A ReadableStream or null. | |
| bodyUsed | Ready-only property. Flag that indicates whether the request body has been read yet.Accepted value: - true: The request body has been read. - false: The request body hasn't been read. Data type: Boolean | |
| cache | Ready-only property. Contains the cache mode of the request which controls how the request interacts with the browser's HTTP cache. Accepted values: - default: The browser looks for a matching request in its HTTP cache. - If there is a match and it is fresh, it is returned from the cache. - If there is a match but it is stale, the browser makes a conditional request to the remote server. If the server indicates that the resource has not changed, it is returned from the cache. Otherwise the resource is downloaded from the server and the cache will be updated. - If there is no match, the browser makes a normal request, and updates the cache with the downloaded resource. - force-cache: The browser looks for a matching request in its HTTP cache. - If there is a match, fresh or stale, it is returned from the cache. - If there is no match, the browser makes a normal request and updates the cache with the downloaded resource. - no-cache: The browser looks for a matching request in its HTTP cache. - If there is a match, fresh or stale, the browser makes a conditional request to the remote server. If the server indicates that the resource has not changed, it is returned from the cache. Otherwise the resource is downloaded from the server and the cache is updated. - If there is no match, the browser makes a normal request, and updates the cache with the downloaded resource. - no-store: The browser fetches the resource from the remote server without first looking in the cache, and does not update the cache with the downloaded resource. - only-if-cached: The browser looks for a matching request in its HTTP cache. - If there is a match, fresh or stale, it is returned from the cache. - If there is no match, the browser responds with 504 Gateway timeout status. The `only-if-cached` mode can only be used if the request's mode is `same-origin`. Cached redirects are followed if the request's `redirect` property is `follow` and the redirects do not violate the `same-origin` mode. - reload: The browser fetches the resource from the remote server without first looking in the cache, but then updates the cache with the downloaded resource. Data type: String | |
| credentials | Read-only. Reflects the value given to the Request\(\) constructor in the credentials option. Credentials are cookies, TLS client certificates, or authentication headers containing a username and password.Accepted values: - include: Always include credentials, even for cross-origin requests. - omit: Never send credentials in the request or include credentials in the response. - same-origin: Only send and include credentials for same-origin requests. Data type: String | |
| destination | Read-only. Returns a string describing the type of content being requested.Accepted values: - audio: The target is audio data. - audioworklet: The target is data being fetched for use by an audio worklet. - document: The target is an HTML or XML document. - embed: The taget is embedded content. - fencedframe: The target is a fenced frame. - font: The target is a font. - frame: The target is a frame. - iframe: The target is an iframe. - image: The target is an image. - json: The target is a JSON file - manifest: The target is a manifest. - object: The target is a object. - paintworklet: The target is a paint worklet. - report: The target is a report. - script: The target is a script. - sharedworker: The target is a shared worker. - style: The target is a style. - track: The target is an HTML <track>. - video: The target is video data. - worker: The target is a worker. - xslt: The target is an XSLT transform. Data type: String | |
| headers | Read-only. The Headers object associated with the request.Data type: Headers object | |
| integrity | Read-only. The subresource integrity value of the request.Value: The value that was passed as the options.integrity argument when constructing the request. If an integrity has not been specified, the property returns ''. | |
| isHistoryNavigation | Read-only. Boolean indicating whether the request is a history navigation.Accepted values: - true: The request is a history navigation. - false: The request is not a history navigation. Data type: Boolean | |
| keepalive | Read-only. The request's keepalive setting \(true or false\). Returns an empty string if an integrity value is not passed in the request.Accepted values: - true: The browser keeps the associated request alive if the page that initiated it is unloaded before the request is complete. - false: The browser doesn't keep the associated request alive if the page that initiated it is unloaded before the request is complete. Data type: Boolean | |
| method | Read-only. The request's method \(`GET`, `POST`, etc.\)Data type: String | |
| mode | Read-only. Mode of the request. Used to determine if cross-origin requests lead to valid responses, and which properties of the response are readable.Accepted values: - cors: If the request is cross-origin then it will use the Cross-Origin Resource Sharing \(CORS\) mechanism. - navigate: A mode for supporting navigation. The navigate value is intended to be used only by HTML navigation. A navigate request is created only while navigating between documents. - no-cors: Disables CORS for cross-origin requests. The response is opaque, meaning that its headers and body are not available to JavaScript. - same-origin: Disallows cross-origin requests. If a request is made to another origin with this mode set, the result is an error. Requests can be initiated in a variety of ways, and the mode for a request depends on the particular means by which it was initiated. For example, when a Request object is created using the Request\(\) constructor, the value of the mode property for that Request is set to cors. However, for requests created other than by the Request\(\) constructor, no-cors is typically used as the mode; for example, for embedded resources where the request is initiated from markup, unless the crossorigin attribute is present, the request is in most cases made using the no-cors mode — that is, for the <link> or <script> elements \(except when used with modules\), or <img>, <audio>,<video>, <object>, <embed>, or <iframe> elements. Data type: String | |
| redirect | Read-only. Mode for how redirects are handled.Valid values: - error - follow - manual Data type: String Default: follow | |
| referrer | Read-only. The referrer of the request \(for example, `client`, `no-referrer`, or a URL\). A value of `no-referrer` returns an empty string.Data type: String | |
| referrerPolicy | Read-only. The referrer policy which governs what referrer information is sent in the Referrer header with the request.Data type: String | |
| signal | Read-only. AbortSignal associated with the request.Data type: String | |
| url | Read-only. URL of the request.Data type: String | |
Parent Topic:Server API reference
Fetch Request - Request()
Creates a new Request object. Optionally create the Request object from a URL or object resource.
| Name | Type | Description |
|---|---|---|
| input | String or Object | Optional. The resource to retrieve.Valid values:
Note: Note the following behavioral updates to retain security while making the constructor less likely to throw exceptions:
|
| options | Object | Optional. A Fetch RequestInit - Scoped, Global object containing any custom settings to apply to the request. If you construct a new request from an existing request, options set in the new request override any corresponding options in the original request.Default: Returns default values for all properties. |
The following example shows how to create a new Request object using the Request() constructor.
var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");
The following example shows how to create the new Request object using the input parameter to retrieve a URL or object.
var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");
fetch(myRequest)
.then((response) => response.blob())
.then((response) => {
var objectURL = URL.createObjectURL(response);
myImage.src = objectURL;
});
The following example shows how to create the new Request object with header options using an object literal.
var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");
var options = {
headers: {
"Cache-Control": "max-age=60480",
},
};
Fetch Request - arrayBuffer()
Reads the request body and returns it as a promise that resolves with an arrayBuffer.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Promise | A promise that resolves with an arrayBuffer. |
The following shows how to create a new request using the arrayBuffer() method.
var myArray = new Uint8Array(10);
var request = new Request("/myEndpoint", {
method: "POST",
body: myArray,
});
request.arrayBuffer().then((buffer) => {
// perform an action with the buffer sent in the request
});
Fetch Request - blob()
Reads the request body and returns it as a promise that resolves with a Blob.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Object | A promise that resolves with a Blob. |
The following example shows how to form a request with the blob() method.
var obj = { hello: "world" };
var myBlob = new Blob([JSON.stringify(obj, null, 2)], {
type: "application/json",
});
var request = new Request("/myEndpoint", {
method: "POST",
body: myBlob,
});
request.blob().then((myBlob) => {
// do something with the blob sent in the request
});
Fetch Request - bytes()
Reads the request body and returns it as a promise that resolves with an Uint8Array.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Object | A promise that resolves with an Uint8Array. |
The following shows how to create a new request using the bytes() method.
var myArray = new Uint8Array(10);
var request = new Request("/myEndpoint", {
method: "POST",
body: myArray,
});
request.bytes().then((buffer) => {
// do something with the buffer sent in the request
});
Fetch Request - clone()
Creates a copy of the current Request object.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Request | A Request object that is an exact copy of the request that clone() was called on. clone() throws a error if the request body has already been used. If you want to modify the request, you use the Fetch Request - Request() constructor. |
The following example demonstrates how to create a new request using request() and then copy it using clone().
var myRequest = new Request("flowers.jpg");
var newRequest = myRequest.clone(); // a copy of the request is now stored in newRequest
Fetch Request - formData()
Reads the request body and returns it as a promise that resolves with a FormData object.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| None | A Promise that resolves with a FormData object. |
The following example demonstrates how to create a new request using request() and then resolve it with the formData() method to resolve it as a FormData object.
var formData = new FormData();
var fileField = document.querySelector('input[type="file"]');
formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);
var request = new Request("/myEndpoint", {
method: "POST",
body: formData,
});
request.formData().then((data) => {
// do something with the formdata sent in the request
});
Fetch Request - json()
Reads the request body, parses the content as JSON, and returns a promise that resolves with the parsed result.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Object | A promise (the eventual completion, or failure, of an asynchronous operation and its resulting value) that resolves to a JavaScript object. This object could be anything that can be represented by JSON: an object, an array, a string, a number, and so on. |
The following example demonstrates how to create a new request using request() and then json() to parse the request and return it as a JSON object.
var obj = { hello: "world" };
var request = new Request("/myEndpoint", {
method: "POST",
body: JSON.stringify(obj),
});
request.json().then((data) => {
// process the data sent in the request
});
Fetch Request - text()
Reads the request body and returns it as a promise that resolves with a String decoded using UTF-8.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| None | A promise that resolves with a String in UTF-8 format. |
This example shows how to call text().
var text = "Hello world";
var request = new Request("/myEndpoint", {
method: "POST",
body: text,
});
request.text().then((text) => {
// process the data sent in the request
});