Artigo original: JavaScript Fetch API Tutorial with JS Fetch Post and Header Examples

Se você está escrevendo uma aplicação para a web, é possível que você tenha de trabalhar com dados externos. Eles podem ser seu próprio banco de dados, APIs de terceiros e assim por diante.

Quando o AJAX apareceu, em 1999, ele nos mostrou uma maneira melhor de criar aplicações para a web. O AJAX foi um marco no desenvolvimento para a web e é o conceito central por trás de muitas tecnologias modernas, como o React.

Antes do AJAX, era preciso renderizar novamente toda a página da web, mesmo para atualizações pequenas. O AJAX, no entanto, nos deu uma maneira de buscar (fetch, em inglês) o conteúdo do back-end e atualizar elementos selecionados da interface do usuário. Isso ajudou os desenvolvedores com a experiência do usuário e a criar plataformas maiores e mais complexas na web.

Curso rápido sobre APIs REST

1-9

Estamos agora na era das APIs RESTful (texto em inglês). De modo simples, uma API REST permite a você enviar (push – traduzido do inglês a partir do significado no contexto) e receber (pull – traduzido do inglês a partir do significado no contexto) dados de um datastore, ou local de armazenamento de dados. Esse local pode ser seu banco de dados ou mesmo um servidor de terceiros, como a API do Twitter.

Há tipos diferentes de APIs REST. Vejamos aqui as que você usará na maioria dos casos.

  • GET — Obter dados de uma API. Por exemplo, obter um usuário do Twitter com base em seu nome de usuário.
  • POST — Enviar dados para a API. Por exemplo, criar um novo registro de usuário com nome, idade e endereço de e-mail.
  • PUT — Atualizar um registro existente com novos dados. Por exemplo, atualizar o endereço de e-mail do usuário.
  • DELETE — Remover um registro. Por exemplo, excluir um usuário de um banco de dados.

Há três elementos para toda API REST. A solicitação, a resposta e os cabeçalhos.

Solicitação (Request) — Esses são os dados que você enviará para a API, como um id de pedido para obter os detalhes do pedido.

2-6
Exemplo de solicitação

Resposta (Response ) — Todos os dados que você receber de volta do servidor após uma solicitação com sucesso/que tenha falhado.

3-5
Exemplo de resposta

Cabeçalhos (Headers ) — Metadados adicionais passados para a API para auxiliar o servidor a entender o tipo de solicitação com a qual ele está lidando, por exemplo, "content-type" (tipo de conteúdo).

4-2-1
Exemplo de cabeçalhos

A vantagem real de usar uma API REST é poder criar uma camada única de API para que diversas aplicações possam trabalhar com ela.

Se você tem um banco de dados que deseja gerenciar usando uma aplicação para a web, dispositivos móveis e desktop, tudo o que precisa é de uma camada única da API REST.

Agora que você já sabe como as APIs REST funcionam, vejamos como podemos consumi-las.

XMLHttpRequest

Antes de o JSON dominar o mundo, o formato principal de troca de dados era o XML. A XMLHttpRequest() é uma função do JavaScript que tornou possível obter dados das APIs que retornavam dados em XML.

A XMLHttpRequest nos deu a opção de buscar dados em XML do back-end sem recarregar toda a página.

Essa função cresceu desde seus primeiros dias em que trabalhava apenas com dados em XML. Agora, ela dá suporte a outros formatos de dados, como o JSON e texto simples.

Vamos escrever aqui uma chamada simples de XMLHttpRequest para a API do GitHub para obter meu perfil.

// função para tratar o sucesso
function success() {
    var data = JSON.parse(this.responseText); //fazer o parsing da string para JSON
    console.log(data);
}

// função para tratar o erro
function error(err) {
    console.log('Erro de solicitação', err); //os detalhes do erro estarão no objeto "err"
}

var xhr = new XMLHttpRequest(); //invocar uma nova instância de XMLHttpRequest
xhr.onload = success; // chamar a função success se a solicitação for um sucesso
xhr.onerror = error;  // chamar a função error se a solicitação der errado
xhr.open('GET', 'https://api.github.com/users/manishmshiva'); // abrir uma solicitação GET
xhr.send(); // enviar a solicitação ao servidor.

O código acima enviará uma solicitação GET para https://api.github.com/users/manishmshiva para obter as informações do meu GitHub em JSON. Se a resposta tiver sucesso, serão impressas as informações seguintes em JSON no console:

5-2-1

Se houver uma falha na solicitação, será impressa essa mensagem de erro no console:

8-1

Fetch API

Fetch API é uma versão mais simples e mais fácil de usar da XMLHttpRequest para consumir recursos de modo assíncrono. Fetch permite que você trabalhe com as APIs REST com opções adicionais como cache de dados, leitura de respostas em streaming e mais.

A maior diferença está no fato de que Fetch trabalha com promises em vez de callbacks. Os desenvolvedores de JavaScript vêm, aos poucos, fugindo das callbacks desde a introdução das promises.

Para uma aplicação complexa, você pode adquirir facilmente o hábito de escrever callbacks, o que leva ao callback hell (texto em inglês sobre "o inferno das callbacks").

Com promises, é fácil escrever solicitações assíncronas e lidar com elas. Se você ainda não conhece bem as promises, pode aprender sobre como elas funcionam aqui (texto em inglês).

Abaixo vemos como a função que escrevemos antes seria se usássemos fetch() em vez de XMLHttpRequest:

// Solicitação GET.
fetch('https://api.github.com/users/manishmshiva')
    // Tratamento do sucesso
    .then(response => response.json())  // converter para json
    .then(json => console.log(json))    //imprimir dados no console
    .catch(err => console.log('Erro de solicitação', err)); // lidar com os erros por catch

O primeiro parâmetro da função Fetch deve sempre ser o URL. Fetch recebe um segundo objeto JSON com opções como método, cabeçalhos, corpo da solicitação e assim por diante.

Há uma diferença importante entre o objeto de resposta (response) de XMLHttpRequest e de Fetch.

XMLHttpRequest returna os dados como uma resposta, enquanto o objeto de resposta de Fetch contém informações sobre o próprio objeto. Isso inclui cabeçalhos, código de status etc. Chamamos a função "res.json()" para obter os dados de que necessitamos do objeto de resposta.

Outra diferença importante é o fato de Fetch API não lançar um erro se a resposta retornar com o código de status 400 ou 500. A resposta ainda será considerada um sucesso e passada para a função 'then'.

Fetch somente lança um erro se a própria solicitação for interrompida. Para tratar de respostas com os status 400 e 500, você pode criar uma lógica personalizada usando 'response.status'. A propriedade 'status' dará a você o código de status da resposta retornada.

Ótimo. Agora que você entende como funciona a Fetch API, vamos examinar mais alguns exemplos de como passar os dados e de como trabalhar com os cabeçalhos.

Trabalhando com os cabeçalhos

Você pode passar os cabeçalhos usando a propriedade 'headers'. Você também pode usar o construtor headers (texto em inglês) para estruturar melhor o seu código. Porém, passar um objeto JSON para a propriedade "headers" deve ser o suficiente na maioria dos casos.

fetch('https://api.github.com/users/manishmshiva', {
  method: "GET",
  headers: {"Content-type": "application/json;charset=UTF-8"}
})
.then(response => response.json()) 
.then(json => console.log(json)); 
.catch(err => console.log(err));

Passando dados em uma solicitação POST

Para uma solicitação POST, é possível usar a propriedade "body" para passar uma string de JSON como entrada. Observe, no entanto, que o corpo da solicitação deve ser uma string de JSON, enquanto os cabeçalhos devem ser um objeto JSON.

// dados a serem enviados pela solicitação POST
let _data = {
  title: "foo",
  body: "bar", 
  userId:1
}

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: "POST",
  body: JSON.stringify(_data),
  headers: {"Content-type": "application/json; charset=UTF-8"}
})
.then(response => response.json()) 
.then(json => console.log(json));
.catch(err => console.log(err));

A Fetch API segue sendo desenvolvida ativamente. Podemos esperar por recursos melhores em um futuro próximo.

Porém, a maioria dos navegadores já dá suporte ao uso de Fetch em suas aplicações. O gráfico abaixo deve ajudar a saber quais navegadores dão suporte a ela em aplicações para a web e dispositivos móveis.

Support

Espero que este artigo tenha ajudado você a entender como funciona a Fetch API. Experimente usar a Fetch em sua próxima aplicação para a web.

O autor escreve regularmente sobre Aprendizagem de Máquina, Ciberssegurança e DevOps. Você pode assinar a newsletter semanal do autor aqui.