Artigos JavaScript JavaScript: Fetch

A API fetch provê ao navegador uma interface para a execução de requisições HTTP através de Promises.

Guia do artigo:

Sintaxe

fetch(input: string, {
    method?: "GET" | "POST" | "PUT" | "DELETE",
    mode?: "navigate" | "same-origin" | "no-cors" | "cors",
    headers?: { [ key: string ]: any }
  }): Promise<Response>
Métodos

A lista a seguir descreve os métodos do objeto.

  • then - permite definir o bloco executado mediante o cumprimento de uma promise retornando um objeto do tipo Response.
  • catch - permite definir o bloco executado mediante a rejeição de uma promise

Na prática

Exemplo 1

Antes do Fetch as requisições HTTP eram feitas através do XMLHttpRequest. Neste exemplo faremos uma comparação da mesma requisição sendo feita em ambas APIs:

// requisição com o XMLHttpRequest
  const request = new XMLHttpRequest()
  
  request.open('GET', 'http://exemplo.com/usuario')
  
  request.onload = function () {
    console.log(JSON.parse(this.responseText))
  }
  
  request.onerror = function () {
    console.log('erro ao executar a requisição')
  }
  
  request.send()

Perceba que na linha 1 é instanciado o XMLHttpRequest a uma constante, e em seguida (linha 2) definimos o método e URL da requisição, para depois declarar dois callbacks: onload e onerror para ação de sucesso e erro, respectivamente. Ao final executamos a requisição com o send().

Todo esse processo torna a requisição complexa de ser feita, sem contar que não foi definido sequer um header no exemplo, por isso foi criado o Fetch, tornando a requisição HTTP mais simples, como podemos ver no exemplo reescrito.

// requisição com o Fetch
  
  fetch('http://exemplo.com/usuario')
    .then(T => T.json())
    .then(console.log)

Exemplo 2

É possível definir o método (GET, POST, PUT, etc.) que será utilizado na requisição. No exemplo abaixo veremos como é feita uma requisição do tipo POST utilizando o Fetch API:

function cadastraUsuario (body) {
    const options = {
      method: 'POST',
      body: Object.keys(body)
        .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(body[k])}`)
        .join('&')
    }
  
    return fetch('http://exemplo.com/usuario', options)
      .then(T => T.json())
  }
  
  cadastraUsuario({ nome: 'Bruno', sobrenome: 'Carvalho de Araujo' })
    .then(() => console.log('cadastrado'))
    .catch(() => console.log('falha ao cadastrar'))

Neste exemplo criamos uma função que serve para efetuar um cadastro de usuário. Perceba que além da URL definimos um objeto com informações, como o método utilizado e o conteúdo (body) da requisição.

Exemplo 3

Considere que seja necessário definir cabeçalhos personalizados como em uma autenticação RESTful. Considerando a requisição do exemplo anterior, podemos fazer pequenas mudanças para adicionar os headers necessários.

...
    const options = {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: Object.keys(body)
        .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(body[k])}`)
        .join('&')
    }
  ...

Perceba que a única diferença para o exemplo anterior foi a adição da propriedade headers contendo os cabeçalhos necessários.

Exemplo 4

É comum ocorrer erros durante requisições HTTP como por exemplo, um servidor não estar funcionando corretamente e retornar um erro 404. Por isso devemos fazer o tratamento destas falhas, como no exemplo a seguir:

fetch('http://exemplo.com/usuario')
    .then(response => {
      // valida se a requisição falhou
      if (!response.ok) {
        return new Error('falhou a requisição') // cairá no catch da promise
      }
  
      // verificando pelo status
      if (response.status === 404) {
        return new Error('não encontrou qualquer resultado')
      }
  
      // retorna uma promise com os dados em JSON
      return response.json()
    })
É importante lembrar que o Fetch não considera erros de requisição a partir do código de retorno, na verdade ele so considera falha quando não recebe uma resposta do servidor.

Exemplo 5

O fetch possui alguns recursos extras, uma delas e a possibilidade de ignorar as restrições do CORS (compartilhamento de recursos de origem cruzada), para isso basta definir no atributo mode o valor no-cors, como no exemplo abaixo:

fetch('http://outroservidor.com/usuario', { mode: 'no-cors' })
    .then(T => T.json())
    .then(usuario => {
      console.log(usuario.nome)
    })

Tipos de resposta possíveis

Ao receber a resposta de uma requisição o fetch conta com uma serie de métodos para fazer a conversão do conteúdo recebido que podemos ver melhor a seguir:

  • json() - retorna a resposta da requisição em formato JSON.
  • clone() - cria um clone da resposta da requisição.
  • redirect() - cria uma nova resposta com uma URL diferente.
  • formData() - retorna o resultado da requisição como um objeto do tipo FormData.
  • arrayBuffer() - retorna a resposta da requisição como um ArrayBuffer.
  • blob() - retorna a resposta da requisição como um Blob.
  • text() - retorna a resposta da requisição como uma string.

Podemos ver abaixo como utilizar estes métodos:

fetch('/api/usuario', { method: 'GET' })
    .then(response => response.text())
    .then(texto => console.log(texto))
    .catch(err => console.log(err.message))

No exemplo perceba que na linha 2 é retornado o método response.text(), isso significa que a proxima resposta da promise será um texto ou ela irá para o bloco catch() na linha 4 caso ocorra uma falha no momento da conversão da resposta para texto.

Compatibilidade

Engine Versão Minima
Node.JS ( V8) 6.4.0
Safari ( WebKit) 11.1
Chrome ( V8) 68
Microsoft Edge ( ChakraCore) 17
Firefox ( Gecko) 61

Nota: O Opera utiliza atualmente grande parte do código do Chrome como base para o seu próprio desenvolvimento e por isso ele não é mencionado nesta listagem.

Confira também

Cursos de JavaScript

Cursos de JavaScript

Curso
Curso de Introdução ao JavaScript

Curso de Introdução ao JavaScript

Curso
Guia de linguagem JavaScript

Guia de linguagem JavaScript

Guia