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
• Na prática
• Compatibilidade

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()
    })

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

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

Curso

Curso de Introdução ao JavaScript

Curso

Guia de linguagem JavaScript

Guia