Publicado em 10 de jul. de 2026 · Kevin BK

O que é API? Como funciona e como usar na prática

Documentação oficial do ViaCEP com exemplo de consulta por CEP — A documentação do ViaCEP mostra como o CEP entra no caminho da consulta e como escolher o formato JSON.

O que significa API?

A sigla vem de Application Programming Interface, ou Interface de Programação de Aplicações. A parte mais importante da definição não é a sigla, mas o papel da interface: ela estabelece como um programa pode pedir dados ou acionar uma função oferecida por outro programa.

Pense na API como um contrato técnico. A documentação informa quais endereços existem, o que deve ser enviado, qual formato será aceito e o que pode voltar. Quem usa a API não precisa conhecer o código interno do serviço; precisa respeitar esse contrato.

Quando um aplicativo de clima mostra a previsão, por exemplo, ele pode consultar um serviço meteorológico. O aplicativo é o cliente, o serviço consultado é o servidor, e a API define a conversa entre os dois.

Como uma API funciona?

Uma consulta começa com uma requisição. Ela combina um endereço, um método, parâmetros e, em alguns casos, cabeçalhos ou um corpo de dados. O servidor recebe esse conjunto, verifica se o pedido é válido e devolve uma resposta com um código de estado e o conteúdo solicitado.

O cliente monta a requisição.
A requisição chega a um endpoint da API.
O servidor valida parâmetros, permissões e limites de uso.
O serviço executa a consulta ou ação.
A resposta volta com um código HTTP e, quando aplicável, dados.

Essa sequência explica por que uma URL que parece correta ainda pode falhar. O endpoint pode exigir um parâmetro, uma chave de acesso, outro método HTTP ou um formato específico no corpo da requisição.

Endpoint

Endpoint é o endereço de uma função ou recurso da API. Em uma API de endereços, pode haver um endpoint para consultar um CEP e outro para pesquisar logradouros. Trocar apenas o domínio não basta: o caminho e os parâmetros também fazem parte do contrato.

Parâmetros

Parâmetros refinam o pedido. Eles podem aparecer no caminho, como o número do CEP, ou depois de um ponto de interrogação na URL. Uma API de filmes pode aceitar título, ano, idioma e página; cada campo muda o recorte da resposta.

Cabeçalhos e corpo

Cabeçalhos carregam informações sobre a requisição, como o formato aceito ou uma credencial. O corpo é usado quando o cliente precisa enviar um conjunto de dados, situação comum em operações de criação e atualização. Nem toda requisição possui corpo.

Como usar uma API pela primeira vez

O teste mais simples usa uma API pública com método GET e sem chave. O ViaCEP permite consultar um CEP brasileiro diretamente no navegador. Abra o exemplo de consulta para o CEP 01001-000:

Consultar o CEP 01001-000 no ViaCEP

A URL contém quatro partes úteis:

https://viacep.com.br: domínio do serviço;
/ws/: caminho-base da consulta;
01001000: parâmetro com os oito dígitos do CEP;
/json/: formato pedido para a resposta.

O navegador deve mostrar um objeto JSON parecido com este:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP"
}

JSON organiza a resposta em pares de chave e valor. A chave logradouro identifica o campo; Praça da Sé é o valor retornado. A resposta real possui outros campos, e alguns podem vir vazios quando a fonte não dispõe daquela informação.

Você também pode fazer essa consulta na página do ViaCEP no DexBase, que apresenta os campos principais em cartões. O dado continua vindo da fonte pública; a página apenas facilita a leitura.

Métodos HTTP: GET, POST, PUT, PATCH e DELETE

O método informa o tipo de operação pretendida. A documentação da API é que determina o comportamento exato, mas estes são os usos mais comuns:

Método	Uso comum	Exemplo
GET	Ler ou pesquisar dados	Consultar um CEP
POST	Criar um recurso ou iniciar uma operação	Cadastrar um pedido
PUT	Substituir a representação de um recurso	Enviar todos os dados atualizados de um cadastro
PATCH	Alterar parte de um recurso	Modificar apenas o telefone
DELETE	Solicitar a remoção de um recurso	Excluir um item salvo

Abrir uma URL no navegador normalmente faz uma requisição GET. Para POST, PUT, PATCH e DELETE, costuma ser necessário usar uma ferramenta de testes, um terminal ou código, porque também pode haver cabeçalhos e corpo de dados.

O que os códigos HTTP informam?

O código HTTP resume o resultado da requisição. Ele não substitui o conteúdo da resposta, mas ajuda a separar sucesso, erro do pedido e falha do servidor.

200 OK: a requisição foi atendida;
201 Created: um recurso foi criado;
400 Bad Request: o pedido está malformado ou contém dados inválidos;
401 Unauthorized: faltou autenticação válida;
403 Forbidden: a identidade pode ser conhecida, mas não tem permissão;
404 Not Found: o endpoint ou recurso não foi encontrado;
429 Too Many Requests: o limite de requisições foi atingido;
500 Internal Server Error: o serviço falhou ao processar o pedido.

Um erro 400 pede revisão da sua requisição. Um erro 500 indica problema no serviço. Essa diferença evita perder tempo alterando o código quando a fonte está temporariamente indisponível.

API pública significa API sem chave?

Não. “Pública” pode significar que desenvolvedores externos têm acesso documentado, mas o serviço ainda pode exigir cadastro, chave, limite de uso ou plano pago. Uma API aberta no navegador e sem autenticação é apenas um dos modelos possíveis.

Chaves de API identificam o projeto que faz a requisição. Elas não devem ser colocadas em páginas públicas, repositórios abertos ou exemplos compartilhados. Se uma chave ficar exposta no navegador, qualquer visitante poderá copiá-la e consumir a cota vinculada à conta.

REST, SOAP, GraphQL e WebSocket: qual é a diferença?

Esses nomes descrevem estilos ou protocolos diferentes de integração. Eles não são níveis de qualidade e podem coexistir em um mesmo produto.

REST: organiza recursos em endpoints e usa operações HTTP. É comum em serviços web que retornam JSON.
SOAP: é um protocolo baseado em mensagens XML e contratos formais. Continua presente em integrações corporativas.
GraphQL: permite que o cliente descreva os campos que deseja receber em uma consulta.
WebSocket: mantém uma conexão bidirecional, útil quando servidor e cliente precisam trocar atualizações em tempo real.

Para começar, não tente escolher pela popularidade. Veja o que o sistema que você precisa integrar oferece e confirme se o formato atende ao fluxo, à segurança e à frequência de atualização do projeto.

Como avaliar uma API antes de depender dela

Um teste bem-sucedido não garante que a fonte seja adequada para produção. Antes de construir uma integração, confira:

documentação com endpoints, parâmetros e exemplos;
identificação de quem mantém os dados;
política de uso e licença;
limites por minuto, dia ou conta;
necessidade de chave, token ou assinatura;
data de atualização e cobertura dos dados;
paginação quando a resposta possui muitos registros;
tratamento previsto para indisponibilidade e mudanças de versão.

APIs gratuitas podem mudar limites ou encerrar endpoints. Quando a informação for essencial, registre a origem, monitore falhas e evite montar o sistema supondo que a resposta sempre chegará completa.

Erros comuns de quem está começando

Confundir API com banco de dados

A API é a interface de acesso. O serviço pode consultar um banco de dados internamente, calcular um resultado ou combinar várias fontes. Quem faz a requisição vê o contrato publicado, não necessariamente a estrutura onde os dados estão armazenados.

Ignorar o formato da resposta

Receber status 200 não significa que o campo desejado está na raiz do JSON. A resposta pode trazer uma lista, um objeto interno ou paginação. Leia a estrutura antes de tentar acessar o valor.

Enviar dados sensíveis em uma URL

URLs podem aparecer em histórico, registros do servidor e ferramentas de monitoramento. Não coloque senha, documento pessoal ou chave secreta em parâmetros de consulta. Use somente o mecanismo de autenticação definido pela documentação.

Não tratar limites e falhas

Uma integração precisa prever resposta vazia, limite 429, lentidão e erro temporário. Sem esse cuidado, uma oscilação da fonte pode quebrar a página inteira ou apresentar dado antigo como atual.

Perguntas frequentes

Preciso saber programar para usar uma API?

Você pode testar APIs GET simples no navegador sem programar. Para enviar autenticação, combinar dados, automatizar consultas ou tratar erros, será necessário usar código ou uma ferramenta própria para requisições.

API e REST são a mesma coisa?

Não. API é o conceito amplo de interface entre programas. REST é um estilo de arquitetura usado por muitas APIs web. Também existem APIs baseadas em SOAP, GraphQL, WebSocket e interfaces de bibliotecas ou sistemas operacionais.

JSON é uma API?

Não. JSON é um formato de representação de dados. Uma API pode devolver JSON, XML, texto, imagem ou outro conteúdo definido no contrato. O formato da resposta é apenas uma parte da integração.

Onde encontrar APIs para testar?

O diretório de APIs do DexBase reúne fontes que podem ser consultadas por tema. Antes de usar uma delas em um projeto, abra a documentação original e confirme autenticação, licença e limites atuais.