Esta tradução está incompleta. Por favor, ajude a traduzir este artigo.

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

A API Fetch fornece uma interface JavaScript para accessar e manipular partes do pipeline HTTP, tais como os pedidos e respostas. Ele também fornece o método global fetch() que fornece uma maneira fácil e lógica para buscar recursos de forma assíncrona através da rede.

Este tipo de funcionalidade era alcançada anteriormente utilizando XMLHttpRequest. Fetch fornece uma alternativa melhor que pode ser facilmente utilizada por outras tecnologias como Service Workers. Fetch também provê um lugar lógico único para definir outros conceitos HTTP-relacionados como CORS e extensões ao HTTP.

Note que a especificação fetch() difere de jQuery.ajax(), principalmente, tendo em mente duas situações:

  • A Promise retornada do fetch() não rejeitará o status do erro HTTP, mesmo que a resposta seja um HTTP 404 ou 500. Em vez disso, ele irá resolver normalmente (com o status ok definido como falso), e ele só irá rejeitar se houver falha na rede ou se alguma coisa impedir a requisição de ser completada.
  • Por padrão, o fetch não enviará nem receberá cookies do servidor, resultando em solicitações não autenticadas se o site depende do uso de uma sessão de usuário (para enviar cookies, a opção credentials do  parâmetro init deve ser definida).

Situação do suporte por navegadores

Fetch support is at a fairly early stage, but progress is being made. It is turned on by default in Firefox 39 and above, and Chrome 42 and above.

If you want to use it now, there is also a Fetch Polyfill available that recreates the functionality for non-supporting browsers. Bear in mind that this is at an experimental stage and not yet feature complete.

Note: There have been some concerns raised that the Fetch spec is at odds with the Streams spec; however, future plans show an intention to integrate Streams with Fetch: read Fetch API integrated with Streams for more information.

Feature detection

Fetch API support can be detected by checking for the existence of Headers, Request, Response or fetch() on the Window or Worker scope. For example, you might do this in your script:

if(self.fetch) {
    // run my fetch request here
} else {
    // do something with XMLHttpRequest?

Making fetch requests

A basic fetch request is really simple to set up. Have a look at the following code:

var myImage = document.querySelector('img');

.then(function(response) {
  return response.blob();
.then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;

Here we are fetching an image across the network and inserting it into an <img> element. The simplest use of fetch() takes one argument — the path to the resource you want to fetch — and returns a promise containing the response (a Response object).

This is just an HTTP response of course, not the actual image. To extract the image body content from the response, we use the blob() method (defined on the Body mixin, which is implemented by both the Request and Response objects.)

Note: The Body mixin also has similar methods to extract other types of body content; see the Body section for more.

An objectURL is then created from the extracted Blob, which is then inserted into the img.

Fetch requests are controlled by the connect-src directive of Content Security Policy rather than the directive of the resources it's retrieving.

Supplying request options

The fetch() method can optionally accept a second parameter, an init object that allows you to control a number of different settings:

var myHeaders = new Headers();

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

.then(function(response) {
  return response.blob();
.then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;

See fetch() for the full options available, and more descriptions.

Checking that the fetch was successful

A fetch() promise will reject with a TypeError when a network error is encountered, although this usually means permission issues or similar — a 404 does not constitute a network error, for example. An accurate check for a successful fetch() would include checking that the promise resolved, then checking that the Response.ok property has a value of true. The code would look something like this:

fetch('flowers.jpg').then(function(response) {
  if(response.ok) {
    response.blob().then(function(myBlob) {
      var objectURL = URL.createObjectURL(myBlob);
      myImage.src = objectURL;
  } else {
    console.log('Network response was not ok.');
.catch(function(error) {
  console.log('There has been a problem with your fetch operation: ' + error.message);

Supplying your own request object

Instead of passing a path to the resource you want to request into the fetch() call, you can create a request object using the Request() constructor, and pass that in as a fetch() method argument:

var myHeaders = new Headers();

var myInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var myRequest = new Request('flowers.jpg', myInit);

.then(function(response) {
  return response.blob();
.then(function(myBlob) {
  var objectURL = URL.createObjectURL(myBlob);
  myImage.src = objectURL;

Request() accepts exactly the same parameters as the fetch() method. You can even pass in an existing request object to create a copy of it:

var anotherRequest = new Request(myRequest,myInit);

This is pretty useful, as request and response bodies are one use only. Making a copy like this allows you to make use of the request/response again, while varying the init options if desired.

Note: There is also a clone() method that creates a copy. This has slightly different semantics to the other copying method — the former will fail if the old request's body has already been read (same for copying a response), whereas clone() won't.


The Headers interface allows you to create your own headers object via the Headers() constructor. A headers object is a simple multi-map of names to values:

var content = "Hello World";
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/plain");
myHeaders.append("Content-Length", content.length.toString());
myHeaders.append("X-Custom-Header", "ProcessThisImmediately");

The same can be achieved by passing an array of arrays or an object literal to the constructor:

myHeaders = new Headers({
  "Content-Type": "text/plain",
  "Content-Length": content.length.toString(),
  "X-Custom-Header": "ProcessThisImmediately",

The contents can be queried and retrieved:

console.log(myHeaders.has("Content-Type")); // true
console.log(myHeaders.has("Set-Cookie")); // false
myHeaders.set("Content-Type", "text/html");
myHeaders.append("X-Custom-Header", "AnotherValue");
console.log(myHeaders.get("Content-Length")); // 11
console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]
console.log(myHeaders.getAll("X-Custom-Header")); // [ ]

Some of these operations are only useful in ServiceWorkers, but they provide a much nicer API for manipulating headers.

All of the Headers methods throw a TypeError if a header name is used that is not a valid HTTP Header name. The mutation operations will throw a TypeError if there is an immutable guard (see below). Otherwise they fail silently. For example:

var myResponse = Response.error();
try {
  myResponse.headers.set("Origin", "");
} catch(e) {
  console.log("Cannot pretend to be a bank!");

A good use case for headers is checking whether the content type is correct before you process it further. For example:

fetch(myRequest).then(function(response) {
  var contentType = response.headers.get("content-type");
  if(contentType && contentType.indexOf("application/json") !== -1) {
    return response.json().then(function(json) {
      // process your JSON further
  } else {
    console.log("Oops, we haven't got JSON!");


Since headers can be sent in requests and received in responses, and have various limitations about what information can and should be mutable, headers objects have a guard property. This is not exposed to the Web, but it affects which mutation operations are allowed on the headers object.

Possible guard values are:

  • none: default.
  • request: guard for a headers object obtained from a request (Request.headers).
  • request-no-cors: guard for a headers object obtained from a request created with Request.mode no-cors.
  • response: guard for a Headers obtained from a response (Response.headers).
  • immutable: Mostly used for ServiceWorkers; renders a headers object read-only.

Note: You may not append or set a request guarded Headers’ Content-Length header. Similarly, inserting Set-Cookie into a response header is not allowed: ServiceWorkers are not allowed to set cookies via synthesized responses.

Response objects

As you have seen above, Response instances are returned when fetch() promises are resolved.

They can also be created programmatically via JavaScript, but this is only really useful in ServiceWorkers, when you are providing a custom response to a received request using a respondWith() method:

var myBody = new Blob();

addEventListener('fetch', function(event) {
    new Response(myBody, {
      headers: { "Content-Type" : "text/plain" }

The Response() constructor takes two optional arguments — a body for the response, and an init object (similar to the one that Request() accepts.)

The most common response properties you'll use are:

  • Response.status — An integer (default value 200) containing the response status code.
  • Response.statusText — A string (default value "OK"),which corresponds to the HTTP status code message.
  • Response.ok — seen in use above, this is a shorthand for checking that status is in the range 200-299 inclusive. This returns a Boolean.

Note: The static method error() simply returns an error response. Similarly, redirect() returns a response resulting in
a redirect to a specified URL. These are also only relevant to Service Workers.


Both requests and responses may contain body data. A body is an instance of any of the following types.

The Body mixin defines the following methods to extract a body (implemented by both Request and Response). These all return a promise that is eventually resolved with the actual content.

This makes usage of non-textual data much easier than it was with XHR.

Request bodies can be set by passing body parameters:

var form = new FormData(document.getElementById('login-form'));
fetch("/login", {
  method: "POST",
  body: form

Both request and response (and by extension the fetch() function), will try to intelligently determine the content type. A request will also automatically set a Content-Type header if none is set in the dictionary.


Specification Status Comment
Fetch Padrão em tempo real Initial definition

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 42
41 behind pref
39 (39)
34 behind pref


Microsoft Edge >38

28 behind pref

Não suportado
Feature Android Firefox Mobile (Gecko) Firefox OS (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Basic support Não suportado Não suportado Não suportado Não suportado Não suportado Não suportado Não suportado

See also

Etiquetas do documento e colaboradores

 Colaboradores desta página: dowgssss, FranciscoJunior, DanZeuss, rennerocha
 Última atualização por: dowgssss,