A Fetch API em JavaScript: um guia prático

A Fetch API é a forma moderna, baseada em promises, de fazer requisições HTTP a partir do navegador. Ela substitui o antigo XMLHttpRequest por uma interface mais limpa que funciona naturalmente com async/await e com streams. Todos os navegadores atuais a suportam.

Uma primeira requisição GET

fetch() retorna uma promise que é resolvida para um objeto Response. Para ler o JSON dela, chama-se response.json(), que por sua vez retorna uma promise:

const res = await fetch('https://api.example.com/articles');
const data = await res.json();
console.log(data);

A mesma coisa sem async/await, com cadeias de .then():

fetch('https://api.example.com/articles')
  .then((res) => res.json())
  .then((data) => console.log(data));

A armadilha: fetch não rejeita em erros HTTP

É o que surpreende quase todo mundo. Uma resposta 404 ou 500 continua sendo um fetch bem-sucedido — a promise só é rejeitada em caso de falha de rede (offline, DNS, CORS). Você mesmo precisa verificar response.ok:

const res = await fetch(url);
if (!res.ok) {
  throw new Error(`HTTP ${res.status} ${res.statusText}`);
}
const data = await res.json();

Enviar dados com POST

Passe um segundo argumento de opções para definir o método, os cabeçalhos e o corpo. Para JSON, serialize o payload e defina o Content-Type:

const res = await fetch('/api/articles', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Olá', body: 'Mundo' }),
});
const created = await res.json();

Cancelar uma requisição

Use um AbortController para cancelar uma requisição — útil para tempos limite ou quando um componente é desmontado:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);

try {
  const res = await fetch(url, { signal: controller.signal });
  const data = await res.json();
} catch (err) {
  if (err.name === 'AbortError') console.log('Requisição expirada');
} finally {
  clearTimeout(timeout);
}

Referência rápida

Tarefa	Como
Ler JSON	await res.json()
Ler texto	await res.text()
Verificar o sucesso	res.ok / res.status
Enviar JSON	body: JSON.stringify(...) + Content-Type
Cancelar	AbortController + signal

Isso cobre os casos do dia a dia. A Fetch API também suporta o streaming de corpos de resposta, uploads com FormData e a clonagem de requisição/resposta — mas os padrões acima dão conta da grande maioria das chamadas reais.