Fetch Headers - Scoped, Global

The Fetch Headers API allows you to retrieve, set, add to, and remove headers from a list of request or response headers.

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): Starts 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.

Fetch Headers - Headers(init)

The Headers() constructor creates a new, empty Headers object. You can also create and pre-populate a new Headers object with list of HTTP headers using the init parameter.

Note:

To add headers to an existing Headers object, use Fetch Headers - append(String name, String value).

Table 1. Parameters

Name	Type	Description
init	Object	Optional. An object literal containing HTTP headers to pre-populate the new Headers object with. Valid values: An object literal with string values, An array of name-value pairs, An existing Headers object (where the new object copies data from the existing object). Default: Creates an empty Headers object

The following example shows how to use the Headers() constructor to create a new Headers object with and without headers.

//Intializes an empty Headers object.
var headers = new Headers();

//Sets the new Headers object with a list of headers.
var httpHeaders = {
  "Content-Type": "application/json", 
  "X-My-Custom-Header": "XYZ", 
}; 

var myHeaders = new Headers(httpHeaders);

Fetch Headers - append(String name, String value)

Adds a new value to an existing header inside a Headers object, or adds the header if it does not already exist.

If the specified header already exists, append() changes its existing value to the specified value. If the specified header already exists and accepts multiple values, append() appends the new value to the end of the value set. To overwrite the old value with a new one, use Fetch Headers - set(String name, String value).

Table 2. Parameters

Name	Type	Description
name	String	Required. The name of the HTTP header to add to the Headers object.
value	String	Required. The value of the HTTP header to add.

Table 3. Returns

Type	Description
None

The following example shows how to add a header using append():

var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.get("Content-Type"); // Returns 'image/jpeg'

Output:

“image/jpeg”

The following example shows how to append a new header that accepts multiple values:

var myHeaders = new Headers(); // Currently empty
myHeaders.append("Accept-Encoding", "deflate");
myHeaders.append("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding"); // Returns 'deflate, gzip'

Output:

{“deflate”, “gzip”} 

Fetch Headers - delete(String name)

Deletes a header from the current Headers object.

Table 4. Parameters

Name	Type	Description
name	String	The name of the HTTP header to delete from the Headers object.

Table 5. Returns

Type	Description
None

The following example shows how to first add a header to the Headers object using append(), and then delete the same header using delete().

var myHeaders =newHeaders();// Currently empty
myHeaders.append("Content-Type","image/jpeg");
myHeaders.get("Content-Type");// Returns 'image/jpeg'

The following example shows that the endpoint returns a value of null if the Headers object is already deleted:

myHeaders.delete("Content-Type");
myHeaders.get("Content-Type");// Returns null, as it has been deleted

Output:

null

Fetch Headers - entries()

Returns an iterator allowing you to cycle through all key-value pairs (represented with strings) contained in the Headers object.

Table 6. Parameters

Name	Type	Description
None

Table 7. Returns

Type	Description
Iterator	Returns an iterator object, where both the key and value pairs are String objects.

The following example shows how to create a test Headers object and then use the entries() method to return an iterator of all values in the Headers object.

// Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the key/value pairs
for (var pair of myHeaders.entries()) {
  console.log(`${pair[0]}: ${pair[1]}`);
}

Output:

content-type: text/xml
vary: Accept-Language

Fetch Headers - forEach(Function callbackFn, Object thisArg)

Executes a callback function once per each key/value pair in the Headers object.

The callback function does not execute for deleted keys but does for existing keys even if the value is undefined.

Table 8. Parameters

Name	Type	Description
callbackFn	Function	Function to execute for each key/value pair in the Headers object. Conforms to the format: callbackFn(string key, string value).
callbackFn.value	String	Value of the header entry.
callbackFn.key	String	Name of the header entry.
callBackFn.object	Header	The Headers object to iterate.
thisArg	Object	Value to use as this when executing callback.

Table 9. Returns

Type	Description
None

The following example logs a line for each key/value pair in the Headers object:

// Create a new test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Cookie", "This is a demo cookie");
myHeaders.append("compression", "gzip");

// Display the key/value pairs
myHeaders.forEach((value, key) => {
  console.log(`${key} ==> ${value}`);
});

Output:

compression ==> gzip
content-type ==> application/json
cookie ==> This is a demo cookie

Fetch Headers - get(String name)

Returns a string of all header values of a specified Headers object, or returns null if the header does not exist.

Table 10. Parameters

Name	Type	Description
name	String	The name of the HTTP header whose headers values you want to retrieve (case-insensitive).

Table 11. Returns

Type	Description
String	The value of the retrieved header (represented as a string), or null if the header is not set. Returns an error if the header does not exist. Returns a type error if the given name is not that of an HTTP header.

The following shows how to create a headers object with multiple headers using append(), and then return the header's values using the get() method.

var myHeaders = new Headers(); // Currently empty
myHeaders.append("Accept-Encoding", "deflate");
myHeaders.append("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding"); // Returns "deflate, gzip"
myHeaders
  .get("Accept-Encoding")
  .split(",")
  .map((v) => v.trimStart()); // Returns [ "deflate", "gzip"

Output:

[ "deflate", "gzip" ]

Fetch Headers - getSetCookie()

Returns all Set-Cookie headers associated with a response.

Table 12. Parameters

Name	Type	Description
None

Table 13. Returns

Type	Description
Array of strings	An array of strings containing the values of all Set-Cookie headers associated with a response. The method returns an empty array if no Set-Cookie headers are set.

The following script example shows how to use getSetCookie() to return the header values associated with the response:

var headers = new Headers({
  "Set-Cookie": "name1=value1",
});

headers.append("Set-Cookie", "name2=value2");

headers.getSetCookie();

Output:

["name1=value1", "name2=value2"]

Fetch Headers - has(String name)

Returns a Boolean indicating whether a Headers object contains the given header.

Table 14. Parameters

Name	Type	Description
name	String	The name of the HTTP header to check whether it exists on the Headers object or not.

Table 15. Returns

Type	Description
Boolean	Flag that indicates whether the specified header exists in the Headers object. A TypeError is returned if the given header is not a valid HTTP header name. Possible values: true: The header exists on the object. false: The header doesn't exist on the object.

The following example uses the Headers() and append() methods to create and set a Headers object with the Content-Type header. The example then uses the has() method to show that the Content-Type header exists on the Headers object but a Accept-Coding header does not.

var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.has("Content-Type"); // Returns true
myHeaders.has("Accept-Encoding"); // Returns false

Output:

true
false

Fetch Headers - keys()

Returns an iterator allowing you to cycle through all keys contained in a Headers object.

Use the Fetch Headers - values() method to return all header keys.

Table 16. Parameters

Name	Type	Description
None

Table 17. Returns

Type	Description
Iterator	Returns an iterator, where header keys are represented as Strings.

The following example shows how to create a Headers object with keys, and then use the keys() method to return a list of available headers.

// Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the keys
for (var key of myHeaders.keys()) {
  console.log(key);
}

Output:

content-type
vary

Fetch Headers - set(String name, String value)

Updates a value of an existing header inside the Headers object, or creates a new header with the given value if the header does not already exist.

To simply append a new value to an existing header without overwriting any data, use the Fetch Headers - append(String name, String value) method.

Table 18. Parameters

Name	Type	Description
name	String	The name of the HTTP header in which to set a new value. Throws TypeError if the given name is not the name of an HTTP header.
value	String	The new value to set for the given header.

Table 19. Returns

Type	Description
None

The following example shows how to set a header in new Headers object using append(), and then reset the value using set().

var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.set("Content-Type", "text/html");

Output:

text/html

The following example shows how to set a value in a Headers object when it accepts multiple values:

myHeaders.set("Accept-Encoding", "deflate");
myHeaders.set("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding");

Output:

gzip

Fetch Headers - values()

Returns an iterator allowing you to cycle through all header values contained in the Headers object.

Use the Fetch Headers - keys() method to return all header values.

Table 20. Parameters

Name	Type	Description
None

Table 21. Returns

Type	Description
String	Returns an iterator, where the header values are represented as strings.

The following example shows how to fist create and set a new Headers object with multiple headers using the append() method, and then return a list of all header values in the new object by calling the values() method. Console.log() logs the line to system logs.

// Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the values
for (var value of myHeaders.values()) {
  console.log(value);
}

Output:

text/xml
Accept-Language