O que é API: como funciona, tipos e exemplos práticos

Quando um aplicativo de clima mostra a previsão, ele não tem uma estação meteorológica dentro do celular. Ele pergunta a outro sistema.

Quando você paga com um cartão em uma loja online, o site não processa o pagamento sozinho. Ele pede a um serviço especializado. Essa conversa entre programas acontece por meio de APIs.

Este guia explica o que é uma API, como funciona uma chamada do começo ao fim, quais são os estilos mais comuns e mostra um exemplo real que você pode reproduzir.

O que é uma API

API é a sigla de Application Programming Interface, ou Interface de Programação de Aplicações. É um conjunto de regras que permite que um programa converse com outro, sem que um precise conhecer o funcionamento interno do outro.

Uma analogia clássica é a do restaurante. Você (o cliente) não entra na cozinha. Você faz o pedido ao garçom, que leva à cozinha e volta com o prato. A API é o garçom: define o que você pode pedir, em que formato e o que receberá de volta.

Isso traz dois benefícios importantes:

• Simplicidade: quem usa a API só precisa saber o que pedir, e não como o serviço faz.
• Segurança e controle: o serviço expõe apenas o que quer, e não abre seus sistemas internos.

O termo é amplo. Existem APIs dentro de sistemas operacionais e de bibliotecas de programação. Neste artigo, o foco são as APIs web, acessadas pela internet.

Como uma chamada funciona

A comunicação segue o modelo cliente-servidor: o cliente faz uma requisição e o servidor devolve uma resposta. Em uma API web, isso usa o protocolo HTTP, o mesmo da web em geral. Para entender a base, veja como funciona a internet.

Uma requisição tem:

• URL (endpoint): o endereço do recurso, como https://api.exemplo.com/clientes/42.
• Método: o que se quer fazer.
• Cabeçalhos (headers): informações extras, como o formato aceito e a autenticação.
• Corpo (body): dados enviados, quando necessário.

E a resposta traz:

• Código de status: um número que indica o resultado.
• Cabeçalhos.
• Corpo: os dados pedidos, muitas vezes em JSON.

Os métodos HTTP mais usados

Códigos de status principais

Os códigos são agrupados por centenas: 2xx indica sucesso, 4xx indica erro do cliente e 5xx indica erro do servidor.

O formato JSON

A maioria das APIs modernas troca dados em JSON (JavaScript Object Notation), um formato de texto simples, legível por pessoas e por máquinas:

{
  "nome": "Maria",
  "idade": 34,
  "ativa": true,
  "cidades": ["Recife", "Olinda"]
}

Ele é composto por pares de chave e valor, listas e objetos aninhados. Praticamente toda linguagem de programação sabe ler e gerar JSON.

Um exemplo real: consultar um CEP

Para não ficar só na teoria, vamos consultar uma API pública e gratuita, a BrasilAPI, que oferece dados como CEPs. Usaremos o CEP da Praça da Sé, em São Paulo, que é um endereço público conhecido.

Com o curl

O curl é uma ferramenta de linha de comando para fazer requisições:

curl https://brasilapi.com.br/api/cep/v2/01001000

Em uma chamada real, feita em setembro de 2026, a resposta foi um JSON como este (formatado aqui para facilitar a leitura):

{
  "cep": "01001000",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Sé",
  "street": "Praça da Sé",
  "service": "open-cep",
  "ibge": { "city": "3550308", "state": "35" },
  "timezoneName": "America/Sao_Paulo",
  "location": {
    "type": "Point",
    "coordinates": { "longitude": "-46.63611", "latitude": "-23.5475" }
  }
}

O código de status foi 200, e o cabeçalho informava que o conteúdo é application/json. Os campos e valores podem mudar conforme o serviço evolui, então consulte a documentação da API antes de depender deles.

Com Python

import requests

resposta = requests.get("https://brasilapi.com.br/api/cep/v2/01001000", timeout=10)
resposta.raise_for_status()

dados = resposta.json()
print(dados["city"], dados["state"])

O que o código faz: envia a requisição GET, levanta um erro se o status indicar falha (raise_for_status), converte o corpo JSON em um dicionário e imprime cidade e estado. O timeout evita que o programa fique esperando para sempre.

Com JavaScript

const resposta = await fetch("https://brasilapi.com.br/api/cep/v2/01001000");
const dados = await resposta.json();
console.log(dados.city, dados.state);

Aqui, fetch faz a requisição, e resposta.json() converte o corpo. Esse código funciona em navegadores modernos e no Node.js. Para escolher entre as duas linguagens, veja Python ou JavaScript: qual aprender primeiro.

E quando dá errado

Ao consultar um CEP inexistente, a mesma API respondeu com o status 404 e uma mensagem de erro em JSON. Um bom programa sempre trata erros: verifica o status, mostra uma mensagem útil e não presume que tudo sempre funciona.

Estilos de API

Nem toda API funciona igual. Os estilos mais comuns:

• REST: descrito por Roy Fielding em sua tese de doutorado, em 2000. Organiza a API em recursos identificados por URLs e usa os métodos HTTP. É o estilo mais popular nas APIs web.
• GraphQL: o cliente descreve exatamente os campos de que precisa em uma consulta, em um único endpoint, o que evita receber dados demais ou de menos.
• gRPC: usa um formato binário eficiente e é comum na comunicação entre serviços internos.
• SOAP: um padrão mais antigo, baseado em XML, ainda encontrado em sistemas corporativos e governamentais.
• WebSockets e eventos: para comunicação contínua em tempo real, como chats e cotações. Também existem webhooks, em que o serviço avisa o seu sistema quando algo acontece.

Ao dizer "API REST", muita gente quer dizer apenas "API web que usa JSON". O REST completo tem regras mais rígidas, e na prática muitas APIs seguem o estilo de forma parcial.

Autenticação e segurança

Muitas APIs exigem que você se identifique. As formas mais comuns:

• Chave de API (API key): um código secreto enviado em cada requisição. Simples, mas quem a obtiver pode usá-la.
• Token de acesso (Bearer): um código temporário, muitas vezes obtido por login.
• OAuth 2.0: um padrão que permite que um aplicativo acesse dados seus em outro serviço sem receber a sua senha, com permissões limitadas.

Cuidados essenciais:

1. Nunca exponha chaves e tokens em código público, em repositórios ou em aplicativos de navegador.
2. Use HTTPS sempre, para proteger a comunicação.
3. Aplique o menor privilégio: peça só as permissões necessárias.
4. Respeite os limites de uso (rate limits) e trate o erro 429.
5. Valide os dados recebidos. Nunca confie cegamente na resposta de uma API externa.
6. Guarde segredos em variáveis de ambiente ou em um gerenciador de segredos.

Sobre proteger credenciais no dia a dia, veja também gerenciador de senhas e passkeys.

Documentação e contratos

Uma API bem feita tem documentação clara, com endpoints, parâmetros, exemplos de resposta, códigos de erro e regras de autenticação. Um padrão muito usado para descrever APIs REST é a OpenAPI, que permite gerar documentação interativa e código automaticamente.

Também é importante o versionamento: quando a API muda, a versão antiga continua funcionando por um tempo, por exemplo em /v1/ e /v2/, para não quebrar quem depende dela.

Onde as APIs aparecem

• Pagamentos: lojas conectadas a serviços de cobrança.
• Mapas e localização: apps que mostram rotas.
• Redes sociais: login com contas existentes.
• Clima, câmbio e dados públicos.
• Inteligência artificial: serviços que oferecem modelos por API. Veja, por exemplo, como chamar um modelo local em Ollama.
• Integrações entre sistemas de uma empresa.
• Bancos e finanças: o Open Finance brasileiro funciona com APIs padronizadas. Veja o que é Open Finance.

Perguntas frequentes

API e site são a mesma coisa?

Não. Um site é feito para pessoas, com páginas visuais. Uma API é feita para programas, e devolve dados, geralmente sem visual. Muitos sites usam APIs por trás.

Toda API é gratuita?

Não. Há APIs gratuitas, com limites, e outras pagas, cobradas por uso ou por plano. Leia os termos e os limites.

Preciso saber programar para usar uma API?

Para o básico, ferramentas visuais e o curl bastam. Para integrar uma API a um sistema, é preciso programar. O roteiro de como aprender a programar do zero ajuda.

O que é um endpoint?

É o endereço específico de um recurso ou de uma operação da API, por exemplo /clientes/42.

O que significa "chamar uma API"?

É fazer uma requisição a ela, geralmente por HTTP, e receber a resposta.

Conclusão

Uma API é um contrato entre programas: define o que se pode pedir, como pedir e o que se recebe de volta. Em APIs web, isso acontece por requisições e respostas HTTP, em geral com dados em JSON, e o estilo REST é o mais comum.

Experimente o exemplo do CEP com curl, Python ou JavaScript, e trate sempre erros, autenticação e limites de uso. Este guia foi revisado em setembro de 2026, e os serviços citados podem mudar suas respostas e regras, por isso consulte a documentação de cada um.

Fontes

• Mozilla. HTTP: visão geral (MDN Web Docs).
• Mozilla. Métodos de requisição HTTP.
• Fielding, R. Architectural Styles and the Design of Network-based Software Architectures (2000).
• OpenAPI Initiative. Especificação OpenAPI.
• BrasilAPI. Documentação.
• IETF. RFC 6749: OAuth 2.0.