The Headers Object: A Safer Way to Manage HTTP Headers

Why it exists

The Headers API exists to provide a standardized, safe, and convenient way to interact with HTTP headers. Using plain JavaScript objects for headers is error-prone; it doesn't enforce correct formatting, prevent setting forbidden headers, or handle the case-insensitivity of header names, all of which the Headers API manages automatically.

The mental model

Think of the Headers object as a specialized Map data structure designed specifically for HTTP headers. It's not a generic key-value store. It understands the rules of HTTP, such as case-insensitive header names and the difference between setting a header (set) versus adding a value to an existing one (append). It provides a layer of safety and convenience over manipulating raw header strings or plain objects.

How it works

A Headers object holds a list of name-value pairs. You can create a new, empty one with new Headers(), or you can get a pre-populated one from a Request or Response object (e.g., response.headers). It offers methods like append(name, value), set(name, value), get(name), has(name), and delete(name). The API automatically handles sanitization, like converting header names to lowercase and stripping whitespace from values. Importantly, some Headers objects are immutable, depending on how they were created.

When to use it

Use the Headers object whenever you work with the Fetch API. It's essential for constructing a Request with custom headers, such as setting an Authorization token or a Content-Type. It is also the standard way to read headers from a Response, like checking Content-Length or Cache-Control to determine how to handle the response body.

When not to use it

The Headers object is tied to the Fetch API and browser/worker environments. Do not use it for managing general key-value data that isn't related to HTTP headers; a standard Map or plain object is better suited for that. In older Node.js environments that do not polyfill the Fetch API, you interact with headers via the native http module's objects, which have a different interface.

One canonical example

A common task is sending a POST request with JSON data. You must set the Content-Type and Accept headers correctly. First, create a new Headers object. Then, append your headers. Finally, pass this object to your fetch call.

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer your-token-here");

fetch("https://api.example.com/data", {
method: "POST",
headers: myHeaders,

body: JSON.stringify({ id: 123 }) });