O que é API e como ela faz sistemas conversarem entre si

Você abre o app do banco, toca em “Pix”, digita uma chave e, antes de confirmar, aparece o nome de quem vai receber. Esse nome não estava no seu celular. O aplicativo mandou um pedido para um servidor, o servidor consultou outra base, e a resposta voltou em menos de um segundo. Quem fez essa conversa acontecer foi uma API.

A sigla vem de Application Programming Interface, interface de programação de aplicações. Parece abstrato, mas a ideia é bem prática: é um contrato que diz como um programa pode pedir algo a outro e o que vai receber de volta.

Em poucas palavras: uma API é a porta de entrada combinada de um sistema. Ela define quais pedidos são aceitos, em que formato eles chegam e como a resposta volta. Quem chama não precisa saber como o outro lado funciona por dentro, só precisa seguir o contrato.

Um garçom entre você e a cozinha

A comparação mais usada é a do restaurante, e ela funciona por um motivo: você não entra na cozinha. Você olha o cardápio (a documentação da API), faz o pedido ao garçom (a requisição) e recebe o prato (a resposta). Se pedir algo que não está no cardápio, o garçom avisa que não dá.

O ponto que a analogia esconde é que o cardápio é um compromisso. Se o restaurante muda o nome dos pratos sem avisar, quem pedia pelo nome antigo fica sem comida. Com APIs é igual: se o time que mantém o serviço renomeia um campo de nome para nome_completo, todo aplicativo que lia nome quebra no mesmo minuto. Por isso APIs públicas costumam ter versão no endereço, como /v1/ e /v2/.

Anatomia de uma requisição HTTP, peça por peça

A maioria das APIs que um dev júnior encontra no trabalho é do tipo web, falando HTTP, o mesmo protocolo que o navegador usa para abrir páginas. O guia de visão geral do HTTP da MDN explica o protocolo em detalhes; aqui vai o que importa para entender uma chamada.

Uma requisição tem quatro partes:

1. Método: o verbo do pedido. GET busca dados, POST cria, PUT ou PATCH altera, DELETE remove.
2. URL (o endpoint): o endereço do recurso, por exemplo https://api.exemplo.com.br/v1/clientes/42.
3. Cabeçalhos: informações sobre o pedido, como o formato aceito e a chave de acesso.
4. Corpo: os dados enviados, quando existem. Um GET normalmente não tem corpo; um POST quase sempre tem.

Veja uma chamada real feita pelo terminal com curl:

curl -X GET "https://api.exemplo.com.br/v1/clientes/42" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN"

E uma resposta típica, em JSON:

{
  "id": 42,
  "nome": "Ana Souza",
  "cidade": "Recife",
  "ativo": true
}

Repare que a resposta não traz HTML, cor ou botão. Traz dados puros. Quem decide como mostrar a Ana Souza na tela é o aplicativo que chamou.

O código de status diz mais do que a mensagem de erro

Toda resposta HTTP vem com um número de três dígitos. Iniciantes costumam ignorar esse número e ler só o texto, e perdem a informação mais confiável da resposta. A lista completa está na página de códigos de status HTTP da MDN, mas estes resolvem a maior parte do dia a dia:

A regra prática: 4xx é culpa de quem chamou, 5xx é culpa de quem respondeu. Se você recebe um 400, não adianta abrir chamado no suporte do serviço antes de reler a documentação. Se recebe 500 repetidamente, o seu código provavelmente está certo. A especificação formal desses significados está na RFC 9110, que define a semântica do HTTP.

REST, GraphQL e as outras formas de desenhar uma API

“API” é o conceito geral. REST, GraphQL, gRPC e SOAP são estilos ou tecnologias para construir uma.

REST

É o estilo que você vai ver em nove de cada dez vagas. Cada recurso tem uma URL (/pedidos, /pedidos/17) e os métodos HTTP dizem a ação. É simples de testar no navegador ou no Postman, e é por onde vale começar.

GraphQL

Em vez de várias URLs, existe um único endpoint, e o cliente escreve uma consulta dizendo exatamente quais campos quer. Resolve bem o problema de telas que precisam de dados de muitos lugares ao mesmo tempo, mas exige mais cuidado no servidor para não deixar consultas pesadas derrubarem o banco.

gRPC e SOAP

O gRPC é comum na comunicação entre serviços internos, quando velocidade importa mais que legibilidade. O SOAP, baseado em XML, aparece em integrações antigas de bancos, seguradoras e órgãos públicos. Ninguém escolhe SOAP para um projeto novo, mas muita gente ainda precisa conversar com um.

Nem toda API passa pela internet

Aqui está um detalhe que confunde quem está começando: API não é sinônimo de API web. Quando você escreve localStorage.setItem("tema", "escuro") em JavaScript, está usando uma API do navegador. Quando o Python lê um arquivo com open(), está usando uma API do sistema operacional por baixo. Bibliotecas também expõem APIs: o conjunto de funções públicas que elas deixam você chamar.

O que une todos esses casos é a mesma ideia de contrato. Você sabe o que pode pedir e o que recebe, sem depender de como foi implementado. É por isso que o termo aparece em tanto lugar diferente do glossário de programação: ele descreve uma relação, não uma tecnologia.

Chave, token e limite: o que protege uma API

Uma API aberta para qualquer um sem controle vira alvo em poucas horas. Os mecanismos mais comuns são:

• Chave de API: uma string fixa enviada no cabeçalho. Simples, mas se vazar num repositório público, qualquer um usa a sua cota.
• Token OAuth ou JWT: credencial temporária, obtida depois de um login, que expira e pode carregar permissões específicas.
• Limite de requisições (rate limit): o serviço aceita, por exemplo, 100 chamadas por minuto por cliente. Passou disso, volta o 429.
• Restrição de origem: só aceita chamadas de IPs ou domínios autorizados.

Um erro clássico de júnior é colocar a chave de uma API paga direto no JavaScript do front-end. Qualquer pessoa abre as ferramentas do navegador e copia. A chave tem que ficar no servidor, e o front-end chama o seu servidor, que chama a API externa. Para um passo mais avançado, vale ler sobre como expor uma API sem abrir IP público, uma técnica usada em produção.

Por que um app comum depende de dezenas delas

Pense num app de delivery. Para mostrar a tela inicial, ele provavelmente consulta a API do próprio backend (restaurantes e cardápios), uma API de mapas (distância e tempo de entrega), uma de pagamento (cartões salvos), uma de notificações e uma de análise de uso. Na hora do pagamento, entra a API do processador do cartão ou do Pix.

Nenhuma dessas empresas construiu mapa, antifraude e envio de push do zero. Elas montaram o produto encaixando APIs, e é isso que permite a um time pequeno entregar um app completo. O lado ruim é a dependência: se a API de mapas fica fora do ar, o seu app também parece quebrado, mesmo que o seu código esteja perfeito. Bons sistemas preveem isso com tempo limite de espera (timeout), nova tentativa e uma mensagem amigável quando o serviço externo falha.

Do conceito à primeira chamada que você mesmo faz

A forma mais rápida de entender API é usar uma hoje. Escolha uma pública e gratuita, como a BrasilAPI (que devolve dados de CEP, bancos e feriados), e faça três coisas:

1. Abra https://brasilapi.com.br/api/cep/v1/01310100 no navegador e veja o JSON.
2. Repita a chamada pelo terminal com curl e observe o código de status com a opção -i.
3. Troque o CEP por um inválido e compare a resposta e o código.

Depois disso, o passo natural é construir a sua. Este tutorial de API REST simples em Python mostra o outro lado do balcão: em vez de fazer o pedido, você passa a ser a cozinha que responde.