Integração entre front e API

Ligar o app React à API: fetch com JSON, CORS, proxy do Vite, endereços por ambiente, estados de erro e atualização otimista.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Descrever o caminho de um cadastro do clique até a resposta da API
  • Enviar dados com fetch usando método, cabeçalho e corpo em JSON
  • Ler uma mensagem de erro de CORS e corrigi-la no servidor ou com o proxy do Vite
  • Configurar o endereço da API por ambiente com VITE_API_URL
  • Tratar tempo esgotado, recusa da API e resposta inválida sem perder os dados, com atualização otimista

Você já tem uma tela React e uma API Node rodando, cada uma no seu canto. A primeira vez que você tenta ligar as duas, quase sempre aparece uma mensagem vermelha sobre CORS no console, e muita gente trava aqui. Nesta aula você entende o caminho completo de um cadastro, do clique no botão até o dado salvo, e aprende a tratar cada coisa que pode dar errado no meio sem fazer a pessoa digitar tudo de novo.

Dois programas, uma conversa

No seu computador, são dois processos separados: o Vite servindo o front em http://localhost:5173 e o Node servindo a API em http://localhost:3000. Cada um ocupa uma porta. O código React roda no navegador da pessoa; o código Express roda no servidor. Eles só se falam por HTTP.

O caminho de um cadastro de despesa

  1. Pessoa → App React: clica em Salvar. A pessoa preencheu descrição e valor. O React lê o estado do formulário.
  2. App React → API :3000: POST /despesas + JSON. O fetch envia um pedido HTTP com o corpo em JSON. A partir daqui o React só espera.
  3. API :3000 → Banco: valida e grava. A API confere os dados de novo, porque não confia no cliente, e grava no banco.
  4. API :3000 → App React: 201 + despesa criada. A API devolve o status 201 e a despesa com o id que o banco gerou.
  5. App React → Pessoa: mostra na lista. O React atualiza o estado, a lista ganha um item e o botão volta a funcionar.

Onde cada tarefa acontece?

No front (navegador) · Na API (servidor)

  • Mostrar “Salvando…” e desativar o botão
  • Avisar que o campo valor está vazio antes de enviar
  • Guardar o que a pessoa digitou se o envio falhar
  • Recusar valor negativo com status 400, mesmo vindo do curl
  • Gerar o id da despesa nova
  • Ler a senha do banco de dados

Enviar dados com fetch

Na aula de JavaScript assíncrono você usou fetch para buscar dados. Para enviar, o fetch recebe um segundo argumento com o método, os cabeçalhos (informações extras sobre o pedido) e o corpo.

Um POST completo para a API de despesas. Explore cada parte.

const resposta = await fetch(API_URL + '/despesas', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ descricao, valor: Number(valor) }),
});
const dados = await resposta.json();
if (!resposta.ok) throw new Error(dados.erro);
  • Endereço: API_URL vem de uma variável de ambiente, como você vai ver adiante. Assim o mesmo código chama a API local em desenvolvimento e a API publicada em produção.
  • Método: Sem isso o fetch faz um GET. POST é o método para criar um recurso novo.
  • Cabeçalho: Avisa a API que o corpo é JSON. É esse cabeçalho que faz o express.json() do servidor ler o corpo e preencher req.body.
  • Corpo: O corpo viaja como texto. JSON.stringify transforma o objeto em texto JSON. O Number converte o valor, porque todo campo de formulário entrega texto.
  • Ler a resposta: Transforma o texto JSON da resposta de volta em objeto. Pode ser a despesa criada ou um { erro }: confira resposta.ok antes de decidir.
  • Conferir o status: O fetch só falha sozinho quando a rede falha. Um 400 ou 500 chega como resposta normal, e é você quem transforma em erro.

Alguém escreveu body: { descricao: 'Mercado', valor: 230 }, sem JSON.stringify. A API responde 400 dizendo “Informe a descrição”. O que aconteceu?

  • O objeto virou o texto [object Object], que não é JSON, e a API não achou os campos
  • A API está com defeito, porque os dados estavam certos
  • Faltou usar o método GET

Complete a função que atualiza parte de uma despesa com PATCH.

async function atualizarDespesa(id, mudancas) {
  const resposta = await fetch(API_URL + '/despesas/' + id, {
    method: '____',
    headers: { 'Content-Type': '____' },
    body: JSON.____(mudancas),
  });
  const dados = await resposta.____();
  if (!resposta.____) throw new Error(dados.erro);
  return dados;
}

CORS: a portaria do navegador

Uma origem é a combinação de protocolo, domínio e porta. http://localhost:5173 e http://localhost:3000 são origens diferentes, porque a porta muda. Por segurança, o navegador não entrega a um site a resposta de outra origem, a menos que o servidor autorize. Essa regra de autorização se chama CORS (Cross-Origin Resource Sharing, compartilhamento entre origens).

Um POST com JSON de outra origem: o navegador pergunta antes

  1. App React → Navegador: fetch POST /despesas. O app em localhost:5173 pede para enviar JSON a localhost:3000. Origens diferentes: o navegador entra em ação.
  2. Navegador → API :3000: OPTIONS (pré-voo). Antes do POST, o navegador manda um pedido de consulta chamado preflight (pré-voo): “a origem 5173 pode mandar POST com JSON?”.
  3. API :3000 → Navegador: Allow-Origin: :5173. A API responde com o cabeçalho Access-Control-Allow-Origin: http://localhost:5173. O porteiro recebeu a autorização.
  4. Navegador → API :3000: POST /despesas. Agora sim o navegador envia o pedido de verdade, com o corpo.
  5. API :3000 → App React: 201 liberado para o app. A resposta também traz a autorização, então o navegador entrega o resultado ao seu código.

A mensagem que aparece no console quando a API não autoriza a origem

Access to fetch at 'http://localhost:3000/despesas' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
TypeError: Failed to fetch
  • O destino: Para onde o seu código tentou ir. Confira se o endereço e a porta são os da API.
  • A origem: De onde o pedido saiu: a página do Vite. É essa origem que a API precisa autorizar.
  • Quem bloqueou: Foi o navegador que bloqueou, não a API. O pedido pode até ter chegado e ter sido processado no servidor.
  • O motivo: A resposta veio sem o cabeçalho de autorização. A correção é no servidor, adicionando esse cabeçalho para a origem certa.
  • O que o seu código vê: Por segurança, o JavaScript não recebe o motivo: só um erro genérico de rede. O motivo de verdade está na linha de cima, no console.

A correção, no server.js, com o pacote cors (npm install cors)

import cors from 'cors';

app.use(cors({ origin: 'http://localhost:5173' }));
app.use(express.json());

O curl cadastra despesas sem problema, mas o app React recebe o erro de CORS acima. Qual é a correção certa?

  • Autorizar a origem do front na API, com o cabeçalho Access-Control-Allow-Origin
  • Usar mode: 'no-cors' no fetch
  • Instalar uma extensão que desliga o CORS no navegador
  • Nada, o CORS protege a API contra o curl

Proxy no desenvolvimento e endereços por ambiente

Existe outro jeito de fugir do CORS durante o desenvolvimento: fazer o próprio Vite repassar os pedidos. Um proxy é um intermediário. O front chama /api/despesas na mesma origem (5173), e o Vite encaminha para localhost:3000. Para o navegador, tudo é uma origem só.

Mas o endereço da API muda de lugar para lugar: /api no seu computador, https://api.minhasdespesas.com.br em produção. Na aula de npm e Vite você viu as variáveis de ambiente com prefixo VITE_. Elas resolvem isso: o código lê import.meta.env.VITE_API_URL, e cada arquivo .env dá o valor do seu ambiente.

Proxy e variáveis de ambiente num projeto Vite

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      // /api/despesas no front vira http://localhost:3000/despesas
      '/api': {
        target: 'http://localhost:3000',
        rewrite: (caminho) => caminho.replace(/^\/api/, ''),
      },
    },
  },
});

.env.development

VITE_API_URL=/api

.env.production

VITE_API_URL=https://api.minhasdespesas.com.br

src/api.js

export const API_URL = import.meta.env.VITE_API_URL;

export async function listarDespesas() {
  const resposta = await fetch(API_URL + '/despesas');
  if (!resposta.ok) throw new Error('Erro ' + resposta.status);
  return resposta.json();
}

Confira o proxy funcionando

A API está rodando na porta 3000 em outro terminal. Na pasta do front, confira a configuração, suba o Vite e chame a API passando por ele.

  1. Mostre o conteúdo do arquivo .env.development.

    cat .env.development
    VITE_API_URL=/api
  2. Suba o servidor de desenvolvimento do Vite.

    npm run dev
      VITE v6.3.5  ready in 412 ms
    
      ➜  Local:   http://localhost:5173/
      ➜  Network: use --host to expose
      ➜  press h + enter to show help
  3. Em outro terminal, peça a lista à porta 5173, no caminho /api/despesas. Quem responde é a API, através do proxy.

    curl http://localhost:5173/api/despesas
    [{"id":1,"descricao":"Mercado","valor":230},{"id":2,"descricao":"Ônibus","valor":4.4}]
  4. Agora gere a versão de produção. Nela, o Vite usa o .env.production, e não existe proxy.

    npm run build
    vite v6.3.5 building for production...
    ✓ 34 modules transformed.
    dist/index.html                   0.46 kB │ gzip:  0.30 kB
    dist/assets/index-B7xQ2kfd.css    1.12 kB │ gzip:  0.58 kB
    dist/assets/index-Dk3pL9aZ.js   146.80 kB │ gzip: 47.21 kB
    ✓ built in 1.21s

Para chamar um serviço de pagamento, alguém criou VITE_CHAVE_SECRETA=sk_live_... no .env.production do front. Qual o problema?

  • Tudo com prefixo VITE_ vai parar dentro do JavaScript público, e qualquer pessoa consegue ler a chave
  • Nenhum, porque o arquivo .env não vai para o Git
  • O nome deveria ser VITE_API_URL, senão o Vite não lê

Tudo o que pode dar errado no caminho

Numa rede de verdade, a resposta pode demorar, não chegar, chegar recusando os dados ou chegar num formato estranho. Uma boa integração trata cada caso com uma mensagem útil e nunca apaga o que a pessoa digitou quando o envio falha.

Uma função de envio que separa cada tipo de falha

export async function criarDespesa(dados) {
  let resposta;
  try {
    resposta = await fetch(API_URL + '/despesas', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(dados),
      signal: AbortSignal.timeout(8000), // desiste depois de 8 segundos
    });
  } catch (erro) {
    if (erro.name === 'TimeoutError') throw new Error('A API demorou demais. Tente de novo.');
    throw new Error('Sem conexão com a API. Confira sua internet.');
  }

  const corpo = await resposta.json().catch(() => null); // corpo que não é JSON vira null
  if (!resposta.ok) {
    throw new Error(corpo?.erro ?? 'Não foi possível salvar (erro ' + resposta.status + ').');
  }
  if (typeof corpo?.id !== 'number') {
    throw new Error('A API respondeu num formato inesperado.');
  }
  return corpo;
}

Repare na última conferência. Mesmo que front e API compartilhem um tipo TypeScript Despesa, o tipo só existe enquanto você programa. Na hora em que a resposta chega, ninguém garante que ela segue o tipo. Conferir o formato em tempo de execução é o que evita uma tela quebrada com undefined.

Que tipo de falha é cada situação?

Rede ou tempo · Recusa da API · Resposta fora do contrato

  • O Wi-Fi caiu no meio do envio e o fetch lançou um erro
  • A API não respondeu em 8 segundos e o pedido foi cancelado
  • Status 400 com { "erro": "O valor deve ser maior que zero" }
  • Status 401 porque a sessão expirou
  • Status 200, mas o corpo é uma página HTML de manutenção
  • Status 201, mas sem o campo id que o contrato promete

A pessoa preencheu um formulário longo e a API respondeu 400 por causa de um único campo. O que a tela deve fazer?

  • Manter tudo preenchido, mostrar a mensagem do servidor e liberar o botão para tentar de novo
  • Limpar o formulário para a pessoa começar do zero
  • Recarregar a página para buscar o estado mais novo
  • Mostrar só “Erro 400” para não confundir

Atualização otimista: mostrar antes de confirmar

Uma atualização otimista mostra o resultado na tela antes da API confirmar, marcado como pendente. Quando a resposta chega, você troca o item provisório pelo definitivo. Se a API recusar, você desfaz: tira o item e mostra o erro. A tela parece instantânea, sem mentir para a pessoa.

Coloque em ordem os passos de um cadastro otimista.

  • Criar um item provisório com um id temporário e marcá-lo como pendente
  • Colocar o item provisório na lista e desativar o botão
  • Enviar o POST para a API
  • Se der certo, trocar o provisório pela despesa com o id real e limpar o formulário
  • Se falhar, tirar o provisório da lista e mostrar o erro mantendo o que foi digitado
  • Reativar o botão em qualquer um dos casos

Um cadastro que não perde nada

A tela usa uma API falsa que se comporta como a de verdade: demora um pouco e recusa valores menores ou iguais a zero. Mantenha os campos #descricao, #valor e o botão, e faça a tela: desativar o botão enquanto salva, mostrar a despesa na lista na hora (otimista), e, se a API recusar, tirar a despesa da lista, mostrar a mensagem num elemento com role="alert" e manter o que foi digitado. Teste com o valor -5.

<div id="root"></div>
body { font-family: system-ui, sans-serif; padding: 16px; color: #1e293b; }
form { display: grid; gap: 6px; max-width: 320px; }
input { padding: 8px; font-size: 1rem; }
button { background: #1d4ed8; color: white; padding: 8px 12px; border: 0; border-radius: 6px; font-size: 1rem; cursor: pointer; }
button:disabled { background: #94a3b8; cursor: wait; }
[role="alert"] { color: #b91c1c; margin: 4px 0; }
ul { padding-left: 18px; }
.pendente { color: #64748b; font-style: italic; }
const { useState, useEffect } = React;

// API falsa: atraso de rede e validação no servidor
const banco = [
  { id: 1, descricao: 'Mercado', valor: 230 },
  { id: 2, descricao: 'Ônibus', valor: 4.4 },
];
let proximoId = 3;
const esperar = (ms) => new Promise((r) => setTimeout(r, ms));

const api = {
  async listar() {
    await esperar(100);
    return banco.map((d) => ({ ...d }));
  },
  async criar(dados) {
    await esperar(250);
    if (!(dados.valor > 0)) {
      const erro = new Error('O valor deve ser maior que zero');
      erro.status = 400;
      throw erro;
    }
    const nova = { id: proximoId++, ...dados };
    banco.push(nova);
    return { ...nova };
  },
};

function App() {
  const [despesas, setDespesas] = useState([]);
  const [descricao, setDescricao] = useState('');
  const [valor, setValor] = useState('');

  useEffect(() => {
    api.listar().then(setDespesas);
  }, []);

  async function salvar(evento) {
    evento.preventDefault();
    const nova = await api.criar({ descricao, valor: Number(valor) });
    setDespesas([...despesas, nova]);
    setDescricao('');
    setValor('');
  }

  return (
    <div>
      <form onSubmit={salvar}>
        <label htmlFor="descricao">Descrição</label>
        <input id="descricao" value={descricao} onChange={(e) => setDescricao(e.target.value)} />
        <label htmlFor="valor">Valor</label>
        <input id="valor" type="number" value={valor} onChange={(e) => setValor(e.target.value)} />
        <button type="submit">Salvar</button>
      </form>
      <ul>
        {despesas.map((d) => (
          <li key={d.id}>{d.descricao}: R$ {d.valor}</li>
        ))}
      </ul>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById('root')).render(<App />);
  • Enquanto salva, o botão fica desativado
  • A despesa aparece na lista antes de a API responder
  • Com valor -5, a despesa sai da lista, um alerta mostra a mensagem da API e o texto digitado continua no campo
  • Depois de confirmadas, cada despesa aparece uma vez só e o botão volta a funcionar
Atualização otimista funciona bem para uma despesa ou uma curtida. Em que tipo de tela ela seria uma má ideia?

Em ações caras ou difíceis de desfazer, como confirmar um Pix, finalizar uma compra ou agendar uma consulta. Ali, mostrar “pago” antes da confirmação pode fazer a pessoa fechar o app achando que deu certo. Nesses casos, mostre o carregando e espere a resposta. Use o otimismo quando a chance de falha é baixa e o erro é fácil de desfazer.

Fechamento

  • Front e API são dois processos em portas diferentes que só conversam por HTTP; o front cuida da experiência e a API das regras e dos segredos.
  • Para enviar dados, o fetch precisa de método, cabeçalho Content-Type: application/json e corpo com JSON.stringify, e você confere resposta.ok.
  • CORS é aplicado pelo navegador e liberado pelo servidor; no desenvolvimento, o proxy do Vite coloca tudo na mesma origem, e VITE_API_URL muda o endereço por ambiente.
  • Trate rede, tempo esgotado, recusa da API e resposta fora do contrato, sempre sem apagar o que a pessoa digitou.
  • Na atualização otimista o item aparece na hora como pendente e é confirmado ou desfeito quando a resposta chega.

Ligue o formulário de despesas à sua API

Conecte o front React à API Node da aula anterior e faça o cadastro aguentar as falhas do mundo real.

  1. Configure o proxy /api no Vite e a variável VITE_API_URL em .env.development e .env.production
  2. Faça o formulário enviar um POST com JSON e mostrar a despesa criada na lista
  3. Ligue o CORS na API só para a origem do front e confirme no painel Network que o pré-voo aparece sem o proxy
  4. Trate tempo esgotado com AbortSignal.timeout, resposta inválida e erro 400 sem perder os dados digitados
  5. Desligue a API no meio de um cadastro e confira que a tela mostra uma mensagem útil e permite tentar de novo

Referências

Cursos relacionados