Capítulo 4.1: Fundamentos da Fetch API

Tempo de estudo: 45 minutos

1. Fetch API: A "Antena Principal" do C.O.P.

Imagine que em seu Centro de Operações de Voo (C.O.P.) há uma enorme antena de rádio para se comunicar com as espaçonaves. Você pode sintonizá-la na frequência certa, enviar um comando e esperar uma resposta.

A Fetch API é uma "antena embutida" semelhante nos navegadores modernos. É uma interface JavaScript padrão para fazer requisições HTTP a servidores. Ela permite:

📡 Enviar "comandos" (GET, POST, PUT, DELETE) para nossa API.
🛰️ Receber "telemetria" (dados JSON) do servidor.
⚙️ Trabalhar assincronamente, sem "congelar" a interface do usuário enquanto aguarda uma resposta.

💡 Analogia espacial:

fetch() é o comando "Antena, estabelecer comunicação!". Você a alimenta com:

Coordenadas do alvo (URL da nossa API).

Tipo de comando (método: GET, POST).

Conteúdo do comando (corpo da requisição, cabeçalhos).

Em resposta, você não recebe os dados em si, mas uma promessa (Promise) de que os dados chegarão.

2. Assincronicidade: Comunicação em velocidades de luz

A comunicação com uma nave espacial distante leva tempo. Você não pode simplesmente parar todo o trabalho do C.O.P. e esperar a resposta. Você envia um comando e continua trabalhando, e quando a resposta chega, o sistema o notifica.

Isso é a assincronicidade. O JavaScript não bloqueia a execução do restante do código enquanto espera uma resposta do servidor. Para gerenciar esse processo, a Fetch API usa Promises.

Uma Promise é um "recibo" de que você enviou uma requisição. Ela tem três estados:

pending (pendente): O sinal ainda está a caminho.
fulfilled (cumprida): A resposta foi recebida com sucesso!
rejected (rejeitada): Ocorreu um erro (por exemplo, sem conexão).

3. Primeira requisição: Descobrir onde está a ISS

Vamos enviar nossa primeira requisição usando fetch. Usaremos um arquivo HTML simples e tags <script>.

Passo 1: Criar index.html Crie um arquivo index.html em uma nova pasta (por exemplo, frontend_fleet_control).

<!DOCTYPE html>
<html lang="pt">
<head>
    <meta charset="UTF-8">
    <title>C.O.P. - Fetch API</title>
</head>
<body>
    <h1>Status de comunicação com a ISS</h1>
    <div id="iss-status">Aguardando dados...</div>

    <script>
        // Nosso código JavaScript estará aqui
    </script>
</body>
</html>

Passo 2: Escrever código com fetch Dentro da tag <script>, adicionaremos nossa primeira requisição fetch para a API pública Open Notify.

// index.html -> <script>

const issApiUrl = 'http://api.open-notify.org/iss-now.json';
const statusDiv = document.getElementById('iss-status');

console.log('Enviando solicitação para obter as coordenadas da ISS...');

fetch(issApiUrl)
    .then(response => {
        // O primeiro .then() lida com a própria resposta HTTP
        console.log('Resposta recebida do servidor!', response);
        // Convertemos o corpo da resposta em JSON, isso também é uma operação assíncrona
        return response.json();
    })
    .then(data => {
        // O segundo .then() recebe os dados JSON já parseados
        console.log('Dados convertidos para JSON com sucesso!', data);
        const position = data.iss_position;
        statusDiv.innerHTML = `A ISS está atualmente aqui:
                               <strong>Latitude:</strong> ${position.latitude},
                               <strong>Longitude:</strong> ${position.longitude}`;
    })
    .catch(error => {
        // .catch() será ativado se ocorrer um erro de rede
        console.error('Erro de comunicação com a ISS!', error);
        statusDiv.textContent = 'Não foi possível obter os dados. Verifique a conexão.';
    });

fetch(url): Envia uma requisição GET. Retorna uma Promise.
.then(callback): Executado quando a Promise é resolvida com sucesso (fulfilled). O primeiro .then recebe um objeto Response.
response.json(): Método que lê o corpo da resposta e o analisa como JSON. Ele também retorna uma Promise!
.catch(callback): Executado se a Promise for rejeitada (rejected), por exemplo, devido a um erro de rede.

Passo 3: Abrir no navegador Basta abrir o arquivo index.html em seu navegador. Você deve ver "Aguardando dados..." ser substituído pelas coordenadas atuais da ISS. Abra o console do desenvolvedor (F12) para ver os logs.

4. "E se...": Tratamento de erros do servidor

E se solicitarmos uma URL inexistente? fetch('http://api.open-notify.org/non-existent-endpoint')

O fetch é construído de tal forma que .catch() só será ativado em erros de rede (sem internet, DNS não encontrado). No entanto, respostas com códigos 404 ou 500 para o fetch são uma resposta recebida com sucesso! Simplesmente contém um código de erro.

Maneira correta de verificar:

fetch('http://api.open-notify.org/non-existent-endpoint')
    .then(response => {
        // Verificamos a propriedade .ok, que é true para status 200-299
        if (!response.ok) {
            // Se a resposta não for "OK", criamos nosso próprio erro para cair no .catch()
            throw new Error(`Erro HTTP! Status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Ocorreu um erro ao executar a solicitação:', error);
    });

response.ok: Este é o seu principal indicador de sucesso.
throw new Error(): "Falhamos" manualmente a cadeia de Promises para cair no bloco .catch.

Quiz para fixação

🚀 Resumo do Capítulo:

Você configurou a "antena principal" do seu MCC e aprendeu a enviar requisições e receber respostas.

📡 Você dominou a sintaxe básica de fetch().
🛰️ Entendeu o que são Promises e como trabalhar com .then() e .catch().
⚙️ Aprendeu a processar corretamente as respostas do servidor, verificando response.ok.

Conexão estabelecida! No próximo capítulo, conectaremos nosso MCC à API da frota espacial que criamos no FastAPI, e aprenderemos a obter e exibir a lista de nossas naves.

📌 Verificação:

Certifique-se de que seu arquivo index.html exibe corretamente as coordenadas da ISS.

Tente quebrar intencionalmente a URL e veja no console do desenvolvedor qual erro será exibido.

⚠️ Se o código não funcionar:

Erro CORS: Se você tentar fazer uma requisição para sua API local do FastAPI (por exemplo, http://127.0.0.1:8000) a partir de um arquivo aberto como file:///..., o navegador bloqueará a requisição devido à política de segurança CORS. Resolveremos este problema no próximo capítulo. Por enquanto, estamos usando APIs públicas que permitem isso.

HTTP/HTTPS: http://api.open-notify.org funciona via HTTP. Alguns navegadores podem avisar sobre isso. Se você estiver trabalhando em um site HTTPS, as requisições para recursos HTTP podem ser bloqueadas.