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