O contrato da API: JSON, estados e CORS

O contrato

O frontend e o backend são dois programas independentes, muitas vezes escritos por pessoas diferentes. Para se entenderem, eles combinam um contrato: quais rotas existem, o que recebem e qual formato têm os dados que retornam.

GET /api/usuarios
→ 200 [ { "id": 1, "nome": "Ana" }, { "id": 2, "nome": "Luis" } ]

Se o backend trocar nome por name, o frontend para de funcionar mesmo que nenhum arquivo do frontend tenha sido tocado. O contrato é frágil: as duas metades dependem de respeitar exatamente os mesmos formatos.

JSON: a língua comum

Por HTTP só trafega texto. JSON (JavaScript Object Notation) é o formato padrão para serializar objetos em texto e reconstruí-los novamente:

• O backend faz JSON.stringify(dados) e envia como corpo.
• O frontend recebe o texto e faz await resposta.json() para recuperá-lo.

Por isso só é possível enviar tipos que o JSON entende (objetos, arrays, strings, números, booleanos, null): nada de funções nem datas como objeto Date.

Códigos de status

Cada resposta HTTP traz um código de status que diz como ela foi:

• 2xx — sucesso. 200 OK, 201 Created (algo foi criado).
• 4xx — erro do cliente. 400 (requisição malformada), 401 (não autenticado), 403 (sem permissão), 404 (não existe).
• 5xx — erro do servidor. 500 (algo falhou no backend).

⚠️ Cuidado: fetch NÃO lança erro com um 404 ou um 500. Só falha se a rede cair. Por isso é preciso olhar resposta.ok (true se o status for 2xx) ou resposta.status para detectar erros do servidor.

CORS: por que o navegador bloqueia outras origens

Uma origem é a combinação de protocolo + domínio + porta (https://meuapp.com). Por segurança, o navegador aplica a same-origin policy: por padrão, uma página de meuapp.com não pode ler a resposta de uma API em outra-api.com. Isso impede que um site malicioso leia dados de outro em seu nome.

CORS (Cross-Origin Resource Sharing) é a forma como o servidor concede permissão explícita. Quando a API quer ser consumida a partir de outra origem, ela responde com um cabeçalho:

Access-Control-Allow-Origin: https://meuapp.com

O navegador o vê e permite que seu código leia a resposta. Se esse cabeçalho faltar, a requisição sai, mas o navegador bloqueia a leitura e você verá o típico erro de CORS no console.

Ponto-chave: o CORS é concedido pelo backend, não pelo frontend. É o servidor que decide quais origens podem ler seus dados.