Revision 770395 of Headers

<p>{{ APIRef("Fetch") }}{{ SeeCompatTable() }}</p>

<p>The <strong><code>Headers</code></strong> interface of the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>&nbsp;allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing. A Headers object has an associated header list, which is initially empty and consists&nbsp;of zero or more name and value pairs. &nbsp;<span style="line-height: 19.0909080505371px;">You can add to this using methods like {{domxref("Headers.append","append()")}} (see {{anch("Examples")}}.)&nbsp;</span>In all methods of this interface, header names are matched by case-insensitive byte sequence.&nbsp;</p>

<p>For security reasons, some headers can only be controller by the user agent. These headers include the {{Glossary("Forbidden_header_name", "forbidden&nbsp;header&nbsp;names", 1)}}&nbsp; and {{Glossary("Forbidden_response_header_name", "forbidden response header names", 1)}}.</p>

<p>A Headers object also has an associated guard, which takes a value of <code>immutable</code>, <code>request</code>, <code>request-no-cors</code>, <code>response</code>, or <code>none</code>. This affects whether the {{domxref("Headers.set","set()")}}, {{domxref("Headers.delete","delete()")}}, and {{domxref("Headers.append","append()")}} methods will mutate the header. For more information see {{Glossary("Guard")}}.</p>

<p>You can retrieve a <code>Headers</code> object via the {{domxref("Request.headers")}} and {{domxref("Response.headers")}} properties, and create a new <code>Headers</code> object using the {{domxref("Headers.Headers()")}} constructor.</p>

<div class="note">
<p><strong>Note</strong>: you can find more out about the available headers by reading our <a href="/en-US/docs/Web/HTTP/Headers">HTTP headers</a> reference.</p>
</div>

<h2 id="Constructor">Constructor</h2>

<dl>
 <dt>{{domxref("Headers.Headers()")}}</dt>
 <dd>Creates a new <code>Headers</code> object.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{domxref("Headers.append()")}}</dt>
 <dd>Appends a new value onto an existing header inside a <code>Headers</code> object, or adds the header if it does not already exist.</dd>
 <dt>{{domxref("Headers.delete()")}}</dt>
 <dd>Deletes a header from a <code>Headers</code> object.</dd>
 <dt>{{domxref("Headers.get()")}}</dt>
 <dd>Returns the first value of a given header from within a <code>Headers</code> object.</dd>
 <dt>{{domxref("Headers.getAll()")}}</dt>
 <dd>Returns an array of all the values of a header within a <code>Headers</code> object with a given name.</dd>
 <dt>{{domxref("Headers.has()")}}</dt>
 <dd>Returns a boolean stating whether a <code>Headers</code> object contains a certain header.</dd>
 <dt>{{domxref("Headers.set()")}}</dt>
 <dd>Sets a new value for an existing header inside a <code>Headers</code> object, or adds the header if it does not already exist.</dd>
</dl>

<div class="note">
<p><strong>Note</strong>: To be clear, the difference between {{domxref("Headers.set()")}} and {{domxref("Headers.append()")}} is that if the specified header does already exist and does accept multiple values, {{domxref("Headers.set()")}} will overwrite the existing value with the new one, whereas {{domxref("Headers.append()")}} will append the new value onto the end of the set of values. See their dedicated pages for example code.</p>
</div>

<div class="note">
<p><strong>Note</strong>: All of the Headers methods will throw a <code>TypeError</code> if you try to pass in a reference to a name that isn't a <a href="https://fetch.spec.whatwg.org/#concept-header-name">valid HTTP Header name</a>. The mutation operations will throw a <code>TypeError</code> if the header has an immutable {{Glossary("Guard")}}. In any other failure case they fail silently.</p>
</div>

<h2 id="Examples">Examples</h2>

<p>In the following snippet, we create a new header using the <code>Headers()</code> constructor, add a new header to it using <code>append()</code>, then return that header value using <code>get()</code>:</p>

<pre class="brush: js">
var myHeaders = new Headers();

myHeaders.append('Content-Type', 'text/xml');
myHeaders.get('Content-Type') // should return 'text/xml'
</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('Fetch','#headers-class','Headers')}}</td>
   <td>{{Spec2('Fetch')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatChrome(42) }}<br />
    {{ CompatChrome(41) }} behind pref<br />
    &nbsp;</td>
   <td>{{ CompatGeckoDesktop(39)}}<br />
    34 behind pref</td>
   <td>{{ CompatNo }}</td>
   <td>
    <p>29<br />
     28 behind pref</p>
   </td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
   <td>{{ CompatNo }}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/ServiceWorker_API">ServiceWorker API</a></li>
 <li><a href="/en-US/docs/Web/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li>
 <li><a href="/en-US/docs/Web/HTTP">HTTP</a></li>
</ul>

<p>&nbsp;</p>