API e FastAPI em palavras simples

API é a forma como os programas se comunicam entre si. Um pede, o outro responde. Usando um marketplace como exemplo, vamos ver do que é feita uma requisição, como ler uma resposta em JSON e o que conferir quando o Claude Code conecta uma fonte externa de dados. No final, esclarecemos rapidamente onde o FastAPI pode aparecer nessa história.

O que é API em palavras simples

API (Application Programming Interface) é uma interface de programação. Ela define quais operações estão disponíveis e as regras para chamá-las. API não existe só em aplicações separadas: bibliotecas, o sistema operacional e o navegador também têm a sua. Através dela, um programa pode pedir a outro programa, ou a uma parte dele, que faça algo e devolva o resultado. Aqui vamos falar principalmente de APIs de rede, aquelas que se acessam por um endereço.

Imagine um restaurante. O(a) senhor(a), como cliente, não vai até a cozinha explicar ao cozinheiro como preparar o prato - diz ao garçom o que quer do cardápio, e ele leva o pedido até a cozinha e traz o prato pronto de volta. A API é o garçom. O programa-cliente faz o pedido através dela, e a cozinha (outro programa) o executa. O(a) senhor(a) não precisa saber como tudo funciona por dentro - basta conhecer o cardápio e entender o que pode pedir e o que vai receber de volta.

No fundo, uma API é um contrato: "pode me chamar assim, e em troca eu devolvo esse tipo de resultado".

Também existe um vídeo curto e engraçado em inglês sobre o assunto, "How API work". É uma ilustração da mesma ideia, não uma explicação do tema. Tudo o que o(a) senhor(a) precisa está no texto abaixo.

Requisição e resposta: o exemplo de um marketplace

Imagine um marketplace para o qual um fornecedor envia produtos a partir do próprio programa. Transferir milhares de itens pelos botões do site seria pouco prático, então o marketplace disponibiliza operações de API. Por exemplo, POST /products adiciona um produto, e GET /reports devolve um relatório.

O endereço de uma operação disponível é chamado de endpoint. Para entender uma requisição, olhe tanto para o endereço quanto para o método HTTP. GET /products e POST /products podem fazer coisas diferentes. Em linhas gerais, GET serve para ler, e POST para enviar dados a processar.

Os dados costumam ser enviados em formato JSON. Chaves agrupam os campos de um objeto, strings vão entre aspas, e uma lista de objetos vai entre colchetes:

{
  "name": "Luminária de mesa",
  "price": 15000,
  "count": 350
}

O cliente envia a requisição, o servidor a processa e devolve a resposta. Abaixo está um esboço simplificado da troca, não um pacote HTTP completo:

POST /products
{ "name": "Luminária de mesa", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created é o status da resposta, e o JSON abaixo dele é o corpo com o resultado. Numa API de verdade, a documentação lista o endpoint, o método, os parâmetros obrigatórios, os cabeçalhos, o formato da resposta e os possíveis erros. E é mais seguro começar com um único objeto de teste, não com o conjunto completo de dados.

Frontend, backend e a API entre eles

A API não serve só para ligar aplicações diferentes. Muitas vezes uma única aplicação por dentro já é composta por dois programas, e eles também se comunicam via API.

O frontend é a parte da aplicação com a qual o(a) senhor(a) trabalha no navegador. Fazem parte dele os botões, as imagens, os menus, os formulários e o comportamento da página. A lógica dele costuma ser escrita em JavaScript. Ele pode fazer cálculos complexos por conta própria, e também chamar o servidor quando precisa de dados ou de uma ação do lado do serviço.

O backend é a parte servidora da aplicação. Ele processa pagamentos, salva pedidos, verifica o acesso, busca produtos. Durante o desenvolvimento o servidor pode rodar no seu computador, e depois da publicação, numa hospedagem. O usuário não recebe o código-fonte dele junto com a página. O navegador recebe as respostas às requisições.

Como eles se comunicam? Pela mesma API. O backend disponibiliza endpoints não só para fornecedores externos, mas também para o próprio frontend:

• o(a) senhor(a) abriu a página - o frontend chama o endpoint /products/list, o backend devolve a lista de produtos, o frontend a exibe de forma organizada;
• o(a) senhor(a) clicou em "comprar" - o frontend envia os dados ao endpoint /orders, o backend registra o pedido.

Ou seja, tanto aplicações diferentes quanto partes de uma mesma aplicação podem se comunicar por API. Neste esquema, o navegador envia a requisição, o backend trabalha com os dados e devolve o resultado. O banco de dados não precisa ficar acessível diretamente ao navegador.

Uma requisição feita pelo navegador

Acima dissemos que o frontend "chama um endpoint" do backend. Vamos ver como isso aparece no código. O navegador tem uma função embutida para isso, chamada fetch. Ela envia uma requisição HTTP ao endereço desejado e devolve a resposta. O corpo da resposta costuma vir em JSON, e ele é convertido em objeto pelo método .json().

Vamos usar como exemplo uma lista de locales, combinações de idioma e configurações regionais. Suponha que o backend já sabe devolver a lista pelo endereço /locales, e o frontend precisa exibi-la. Digamos que o servidor devolva:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Como a resposta chega

O trecho abaixo roda dentro de uma função assíncrona do handler da página. Ele busca os dados; a renderização da tabela não é mostrada aqui.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Agora locales contém os dados da tabela

Verificamos res.ok antes de ler os dados. Um erro HTTP como 404 ou 500 não faz, por si só, o fetch lançar uma exceção. Além disso, a própria requisição de rede pode falhar, ou o JSON pode não ser interpretado. O código da página precisa capturar o erro de um trecho como esse e mostrar uma mensagem clara. São causas diferentes, ainda que, em todos os casos, o usuário fique sem os dados. Mais detalhes no guia do MDN sobre fetch.

Há alguns detalhes aqui fáceis de passar despercebidos:

• por padrão o fetch faz um GET, uma requisição para obter dados. Outras operações definem o método explicitamente; por exemplo, nosso marketplace aceita um novo produto via POST;
• o endereço /locales é relativo. Numa página HTTP comum, ele aponta para a raiz do mesmo origin. O origin é definido pelo esquema, pelo host e pela porta; o servidor precisa ter essa rota;
• fetch e .json() não devolvem o resultado na hora, por isso se escreve await antes deles, algo como "espere pela resposta".

Se o(a) senhor(a) abrir o HTML como arquivo pelo file://, a string /locales não vira o endereço do seu servidor HTTP. Para este exemplo, a página é aberta através de um servidor que implementa a rota. O próprio arquivo HTML não cria essa rota.

O frontend e a API podem estar em origins diferentes. Nesse caso, para que o navegador consiga ler a resposta, o servidor da API precisa permitir esse acesso via CORS. É o mecanismo de acesso entre origens, não um nome genérico para qualquer erro de rede. Colocar a página e a API no mesmo origin simplifica o exemplo (nem toda aplicação real precisa fazer isso). Os detalhes estão no artigo do MDN sobre CORS.

Quem responde ao navegador

Quem responde a fetch("/locales")? O backend, e ele não precisa ser Python com FastAPI. API é um acordo entre programas, não uma linguagem específica. O mesmo endpoint pode ser escrito em Node.js, Go ou Java. Por exemplo, o handler de um servidor Node.js pode devolver um array locales já preparado. Abaixo há só um fragmento do handler, não um servidor pronto:

// req e res vêm do handler, locales já foi preparado antes
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

De fora, continua sendo a mesma requisição HTTP GET /locales, e a resposta traz o status 200 e JSON. O frontend não precisa saber em que o backend foi escrito. Ele precisa do endereço, das regras da requisição e do formato da resposta.

Tipos de API

É útil separar as APIs por dois critérios:

• locais e de rede - por exemplo, a API de uma biblioteca é chamada de dentro do código do programa, enquanto uma API de rede é acessada pela rede. Essa rede também pode ser interna, sem acesso à internet pública;
• públicas e internas - as públicas são voltadas a desenvolvedores externos, as internas ligam partes de um sistema. Uma API pública também pode exigir cadastro, pagamento e permissões.

APIs web costumam usar HTTP, um protocolo de requisição e resposta. REST, nome que o(a) senhor(a) vai encontrar na documentação, descreve uma abordagem para projetar APIs; nem toda API HTTP segue o REST automaticamente. Por enquanto é mais útil aprender a ler o código de status numa resposta:

• 200 - tudo certo;
• 201 - criado (por exemplo, um novo objeto depois de um POST);
• 404 - não encontrado;
• 401 - a requisição não traz dados de autenticação válidos;
• 429 - requisições em excesso;
• 500 - erro interno do servidor.

Não é preciso se aprofundar nisso agora. O importante é captar a própria ideia da troca de requisições e respostas. Por enquanto, isso já basta.

Por que um serviço quer uma chave de acesso

Muitos serviços primeiro pedem para o(a) senhor(a) obter uma chave de API, uma string ligada à sua conta ou ao seu projeto. Ela é passada da forma indicada na documentação, muitas vezes num cabeçalho da requisição. O serviço confere o acesso e pode registrar quantas requisições o(a) senhor(a) já fez. Em outras integrações vai aparecer a palavra token. Ele serve para algo parecido, mas a forma de obtenção, a validade e o que ele permite fazer podem ser diferentes.

Sem o acesso correto a requisição não passa; por exemplo, o servidor pode responder 401. Exceder a frequência de requisições costuma ser sinalizado com o código 429. O sentido exato da resposta e os limites permitidos ficam na documentação de cada serviço. E existem fontes abertas que nem precisam de chave.

Onde procurar uma API pronta

É por API que mapas, previsão do tempo, pagamentos e entregas entram nas aplicações. A documentação aberta ajuda a entender o que um serviço faz, mesmo antes de conectá-lo. É melhor começar pela própria tarefa. Defina que dados são necessários, com que frequência devem ser atualizados e o que o(a) senhor(a) pretende fazer com eles.

Para buscar, vale a pena olhar o Postman Public API Network, um catálogo de APIs e exemplos de requisições. O exemplo encontrado ali é só um ponto de partida. O endereço, o formato, o acesso e os limites devem sempre ser conferidos na documentação oficial do dono do serviço.

Onde entra o FastAPI

FastAPI é um dos frameworks para criar APIs e servidores web em Python. Ele pode ligar um endpoint ao seu código de servidor, receber uma requisição e devolver uma resposta em JSON. O FastAPI é necessário quando o(a) senhor(a) está criando o próprio backend em Python; para usar uma API pronta, não é preciso estudá-lo. No nível 7 basta reconhecer o nome e entender essa fronteira.

Como isso funciona junto com o Claude Code

Com esses conceitos em mãos, fica mais fácil avaliar o trabalho do agente. Ele pode ler a documentação de uma API de terceiros, escrever uma requisição do lado cliente ou criar a sua própria API com FastAPI. O que importa é o(a) senhor(a) conseguir ver o caminho concreto, da requisição até os dados na página. Quem envia a requisição, quem responde e como a resposta é tratada?

Por exemplo, para um radar de terremotos existe o feed público GeoJSON do USGS. O endereço da lista da última hora:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Abaixo, um pequeno exemplo didático da estrutura da resposta, com um evento fictício e um conjunto reduzido de campos. Não são os dados atuais do USGS:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Ponto de exemplo" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

Em features fica um array de eventos. O caminho features[0].properties.mag leva à magnitude do primeiro. O índice 0 significa o primeiro elemento do array. As coordenadas vêm na ordem "longitude, latitude, profundidade em quilômetros". O agente pode usar a magnitude para o tamanho do ponto, e as coordenadas para a posição dele. Se o array estiver vazio, não há primeiro elemento; se a magnitude for null, o valor é desconhecido, o que não é o mesmo que um evento de força zero.

Resta decidir o que mostrar depois da requisição:

Enquanto a requisição está em andamento, a página pode mostrar um estado de carregamento. Para testar os diferentes desfechos, respostas simuladas ajudam bastante. Assim o(a) senhor(a) não precisa esperar uma falha real do serviço ou um novo terremoto.

Uma tarefa para o Claude Code agora pode soar assim:

Conecte a página aos dados da API indicada.
Primeiro confira a documentação oficial: endereço, método,
formato da resposta e condições de acesso. Mostre quais campos você usa.
Trate o carregamento, a lista vazia e o erro de atualização.
Se usar dados antigos depois de uma falha, sinalize isso na página.
Não coloque a chave secreta no código do lado cliente.
Teste o resultado e diga quais estados você conseguiu verificar.

Terminado o trabalho, olhe a própria requisição e o resultado dos testes, não só a página pronta. Diferencie também o acesso do agente e o acesso da página. O MCP pode conectar uma ferramenta ao Claude Code, mas a aplicação publicada precisa da própria integração. Encerrar a sessão do agente não deve interromper as requisições do site, se elas estiverem implementadas na própria aplicação.