Você abre um app de previsão do tempo e a previsão de amanhã aparece em um segundo. Quem calculou não foi o seu celular: o app enviou uma mensagem curta ao servidor do serviço meteorológico pedindo os dados de uma cidade e recebeu de volta algumas linhas de dados simples, que transformou em ícones e números. O mesmo acontece quando o checkout de uma loja online pede a uma empresa de pagamentos que cobre o seu cartão, ou quando um colega diz: "é só usar a API deles, aqui está a sua chave".
Este artigo acompanha uma chamada de API da requisição até a resposta, com a saída real do nosso próprio teste, e depois trata de métodos, códigos de status, tipos de API, chaves, limites de taxa, versionamento e segurança das chaves.
O que é uma API?
Uma API é a forma combinada pela qual um software pede a outro dados ou uma ação. A sigla vem de application programming interface: "interface" porque é o ponto de encontro entre dois programas, e "programação" porque quem a usa é o código, não uma pessoa clicando em uma tela.
Um caixa eletrônico é uma boa imagem do dia a dia. Ele oferece um menu curto e fixo (consultar saldo, sacar, trocar a senha) e você nunca vê o cofre por trás dele. O cartão e a senha provam quem você é, um limite diário define quanto você pode sacar e um problema recebe uma mensagem curta como "saldo insuficiente". Uma API funciona do mesmo jeito: uma lista fixa de requisições, uma chave que identifica quem chama, limites de uso e respostas de erro claras.
Sistemas operacionais e navegadores também oferecem APIs, mas no uso cotidiano "uma API" significa uma API web: um serviço que você chama pela internet com HTTP, o protocolo que o seu navegador usa para carregar páginas.
Como funciona uma chamada de API?
Uma chamada de API é uma requisição de um programa a uma API mais a resposta que volta. Ela passa sempre pelas mesmas etapas:
- O cliente monta uma requisição. O cliente (um app, um script ou um servidor) escolhe um método (o que fazer), um endpoint (o endereço da operação), cabeçalhos (detalhes extras, como a chave) e, em alguns métodos, um corpo com dados.
- A requisição chega ao servidor por uma conexão HTTPS criptografada, depois que o DNS converteu o nome do servidor em um endereço IP.
- O servidor verifica quem chama: esta chave pode usar este endpoint e ainda está dentro dos seus limites?
- O servidor faz o trabalho, como ler um banco de dados ou iniciar um pagamento.
- O servidor responde com um código de status que diz como foi, cabeçalhos e, em geral, um corpo com os dados.
- O cliente lê a resposta. Primeiro confere o código de status e depois pega pelo nome os campos de que precisa.
Como são uma requisição e uma resposta de API?
Uma requisição é um método e um endpoint, cabeçalhos e às vezes um corpo; uma resposta é um código de status, cabeçalhos e quase sempre um corpo:
| Parte | Na requisição | Na resposta |
|---|---|---|
| Primeira linha | Método + endpoint | Código de status |
| Cabeçalhos | Chave, formato dos dados | Formato dos dados, limites |
| Corpo | Dados a enviar (opcional) | O resultado, muitas vezes JSON |
Você pode ver isso com o curl, uma ferramenta gratuita de linha de comando para enviar requisições web. O JSONPlaceholder é uma API pública de testes que não pede conta nem chave, então é um lugar seguro para experimentar:
curl -i https://jsonplaceholder.typicode.com/todos/1Na nossa máquina de testes, isso retornou HTTP/1.1 200 OK, o cabeçalho Content-Type: application/json; charset=utf-8 e este corpo:
{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}A opção -i também mostra a linha de status e os cabeçalhos e, sem uma opção de método, o curl envia GET, que significa "ler". Um POST para /todos com um pequeno corpo JSON voltou como 201 Created com um novo "id": 201; esta API de testes apenas finge salvar o registro, e é isso que a torna segura para praticar. Pedir /todos/999999, um registro que não existe, retornou 404 Not Found.
O formato do corpo é JSON (JavaScript Object Notation): texto simples feito de nomes e valores que quase toda linguagem de programação consegue ler. O seu padrão, a RFC 8259, exige UTF-8 entre sistemas e define o tipo de mídia application/json, o valor do cabeçalho acima. APIs mais antigas costumam responder em XML.
Quais métodos HTTP as APIs usam?
O método é o verbo de uma requisição: ler, criar, alterar ou remover. A RFC 9110, o padrão que define o significado das mensagens HTTP, chama alguns métodos de "seguros" (só leem) e alguns de "idempotentes" (enviar a mesma requisição duas vezes tem o mesmo efeito que enviá-la uma vez).
| Método | Tarefa típica | Seguro | Idempotente |
|---|---|---|---|
GET | Ler um registro ou uma lista | Sim | Sim |
POST | Criar um registro, iniciar uma ação | Não | Não |
PUT | Substituir um registro | Não | Sim |
PATCH | Alterar parte de um registro | Não | Não por padrão |
DELETE | Remover um registro | Não | Sim |
A diferença importa quando uma conexão cai no meio do caminho. Repetir um GET não causa problema; repetir um POST pode criar um segundo pedido ou um segundo pagamento. Por isso muitas APIs aceitam uma chave de idempotência junto com um POST, um valor único que diz ao servidor "se você já fez esta, não faça de novo".
O que significam os códigos de status de uma API?
O código de status é o número de três dígitos no topo de cada resposta, e o primeiro dígito diz quem é o responsável: 2 significa sucesso, 3 que o cliente precisa dar mais um passo, como seguir um redirecionamento, 4 que a requisição estava errada e 5 que o servidor falhou. Os códigos que você mais vai encontrar com APIs:
200 OKe201 Created: a requisição funcionou; 201 significa que um novo registro foi criado.400 Bad Request: a requisição está malformada, muitas vezes por um campo ausente ou um JSON quebrado.401 Unauthorized: nenhuma chave ou token válido foi enviado.403 Forbidden: o servidor sabe quem você é, mas você não tem permissão para fazer isso.404 Not Found: o endpoint ou o registro não existe.429 Too Many Requests: você ultrapassou o limite de taxa.500 Internal Server Error: o servidor falhou ao processar a requisição.
Uma API bem construída também explica o erro no corpo. Quando chamamos sem token o endpoint /me da nossa própria API, ela retornou 401 Unauthorized, um cabeçalho www-authenticate: Bearer que indica o esquema esperado e um corpo JSON com um código de erro, uma mensagem de uma linha (Missing or malformed Authorization header) e um ID de requisição para informar ao suporte.
Quais tipos de API existem?
As APIs web diferem principalmente na forma das requisições, e quatro estilos cobrem quase tudo o que você vai encontrar:
| Tipo | Como você pede | Uso típico |
|---|---|---|
| REST | Um endereço por recurso | A maioria das APIs web públicas |
| GraphQL | Um endpoint, você lista os campos | Apps que precisam de dados flexíveis |
| gRPC | Chamadas definidas em um arquivo de esquema | Entre serviços internos |
| Webhook | O serviço chama você | Avisos de eventos |
REST (representational state transfer) dá a cada coisa o seu próprio endereço, como /orders/42, e age sobre ela com os métodos HTTP acima. Quando alguém diz "uma API" sem mais detalhes, quase sempre quer dizer uma API JSON no estilo REST. GraphQL envia todas as requisições a um único endpoint, e a consulta do cliente lista exatamente os campos que ele quer receber. gRPC define cada chamada de antemão em um arquivo de esquema e, por padrão, envia os dados como Protocol Buffers, um formato binário compacto.
Os webhooks invertem a direção: em vez de fazer o seu programa perguntar "tem algo novo?" a cada minuto, você dá ao serviço uma URL sua, e ele envia uma requisição para lá quando algo acontece, como "pagamento recebido".
As APIs também diferem em quem pode usá-las. Uma API pública está aberta a qualquer desenvolvedor que se cadastre; uma API de parceiros (partner), só a empresas com contrato, como a integração de vendedores de um marketplace; e uma API privada, só aos apps e serviços da própria empresa.
O que é uma chave de API e qual a diferença para um token?
Uma chave de API é uma sequência secreta longa que identifica o programa que chama a API, como o cartão no caixa eletrônico. O servidor a verifica em cada requisição para decidir quem está chamando, o que essa pessoa ou programa pode fazer e quais limites se aplicam, e ela costuma continuar válida até você revogá-la.
Um token faz o mesmo trabalho, mas normalmente é emitido por menos tempo ou para um fim mais restrito. O OAuth 2.0 é o padrão por trás da maioria das telas de "conectar sua conta": você aprova um app na própria página do serviço, e o app recebe um token de acesso limitado às permissões (scopes) que você aprovou, sem nunca ver a sua senha. Muitos desses tokens são tokens bearer, definidos na RFC 6750: quem tiver um pode usá-lo, por isso ele vai no cabeçalho Authorization e nunca na URL de uma página.
| Método | O que prova | Uso típico |
|---|---|---|
| Chave de API | Qual programa ou conta chama | Chamadas entre servidores |
| Token OAuth | O que um usuário permitiu a um app | Contas conectadas |
| Lista de IPs permitidos | De onde vem a chamada | Bancos, exchanges, B2B |
Você obtém uma chave na seção de desenvolvedores ou de API da sua conta no site do serviço: crie a chave, marque só as permissões de que ela precisa e copie, porque muitos serviços mostram a chave completa uma única vez. A nossa própria API, descrita na seção Docs deste site, aceita um token bearer apenas no cabeçalho Authorization, nunca na URL nem em um cookie, e cada token carrega scopes, então um token somente leitura não consegue fazer um pedido.
O que é um limite de taxa?
Um limite de taxa (rate limit) é o número de chamadas que alguém pode fazer em um determinado tempo, por exemplo 60 requisições por minuto por chave. Ele protege o serviço contra sobrecarga e impede que um único usuário pesado deixe todos os outros mais lentos. Acima do limite, a API responde 429 Too Many Requests até a janela ser reiniciada.
Muitas APIs informam a sua cota nos cabeçalhos de resposta. A nossa envia X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset em cada resposta; esses nomes são uma convenção comum, não um padrão fixo, então confira a documentação de cada API. Como lidar com o erro quando ele aparece é explicado em 429 Too Many Requests: o que é o erro de rate limit.
Como as APIs são versionadas e documentadas?
As APIs são versionadas para que uma mudança no servidor não quebre os programas que já as chamam. A forma mais visível é colocar a versão no caminho, como na nossa URL base https://api.proxynet.io/api/v1: mudanças incompatíveis vão para v2, e v1 costuma continuar funcionando por um período anunciado. Algumas APIs colocam a versão em um cabeçalho.
A documentação é o contrato da API: cada endpoint com o seu método, os seus parâmetros, uma resposta de exemplo e os seus erros. Muitas APIs a publicam no formato da OpenAPI Specification, um arquivo JSON ou YAML que descreve uma API HTTP tanto para pessoas quanto para ferramentas (a versão 3.2.1 saiu em 10 de setembro de 2026). A partir desse arquivo, as ferramentas podem gerar uma referência, criar código de cliente ou montar um painel para testar as chamadas.
Como manter uma chave de API segura?
Trate uma chave de API como uma senha: quem a tiver pode agir em seu nome e, em uma API paga, gastar o seu dinheiro. A maioria dos vazamentos é simples:
- Chaves no código. Uma chave colada em um script acaba em um repositório Git; guarde-a em uma variável de ambiente ou em um gerenciador de segredos.
- Chaves no código do front-end. Tudo o que é entregue a um navegador ou a um app móvel pode ser lido pelos usuários; chame a API a partir do seu servidor.
- Chaves em URLs. As URLs ficam nos logs do servidor e no histórico do navegador.
- Uma chave para tudo. Dê a cada integração a sua própria chave com o mínimo de permissões, para poder revogar um vazamento isoladamente.
- Chaves que nunca mudam. Faça a rotação periodicamente e logo após um vazamento: crie a nova chave, troque para ela e apague a antiga.
Do lado do provedor, o API Security Top 10 da OWASP Foundation reúne as falhas de API mais comuns. A primeira da lista de 2023 é a autorização quebrada em nível de objeto (Broken Object Level Authorization): um endpoint que devolve o registro 42 a quem pedir, sem verificar se ele pertence a quem chama.
Qual a diferença entre uma API e web scraping?
Uma API devolve os dados que um provedor escolhe compartilhar, em um formato documentado e com limites por escrito; o web scraping baixa páginas feitas para pessoas e extrai os dados do HTML. A API é mais estável quando traz os campos de que você precisa, enquanto o scraping cobre o que nenhuma API oferece, mas quebra quando o layout muda. Os dois caminhos são comparados, com os mesmos dados obtidos das duas formas, em Web scraping vs. API: qual você deve usar?.
Por que algumas APIs só aceitam chamadas de certos endereços IP?
Algumas APIs verificam de onde vem uma chamada, além de qual chave ela carrega. Bancos, exchanges de criptomoedas, marketplaces e muitos serviços de dados para empresas deixam você registrar endereços IP para uma chave, uma lista de IPs permitidos (IP allowlist), e recusam chamadas de qualquer outro lugar, de modo que uma chave roubada não funciona na máquina de outra pessoa.
Aí o seu programa precisa de um endereço de saída fixo, algo que conexões residenciais, notebooks e muitas funções em nuvem não têm; as opções são comparadas em IP estático para API: como resolver o erro de autorização.
Para ambientes de teste e integrações que não envolvem dados de pagamento nem de saúde, os Proxies ISP dão a um script um IP dedicado para você registrar.
Os Proxies de datacenter fazem o mesmo com um endereço de data center. Os dois vêm com restrição de sites de destino por padrão, então você informa o host da API ao fazer o pedido. Para integrações de pagamento e de saúde, registre o endereço do seu próprio servidor.
Onde você encontra APIs
- Apps de celular que buscam previsão do tempo, mensagens e mapas nos seus servidores.
- Checkouts de lojas online, em que a loja chama a API de uma empresa de pagamentos para cobrar um cartão.
- Botões "Fazer login com…", que compartilham um perfil limitado com outro site.
- Apps de finanças pessoais que mostram saldos de vários bancos, quando o banco oferece uma API para isso.
- Rastreamento de encomendas na página de uma loja, alimentado pela API da transportadora.
- Recursos de IA dentro de outros produtos, que enviam o seu prompt a um modelo de linguagem pela API dele.
Erros comuns
- Ignorar o código de status. Ler como dados o corpo de um
401ou429gera resultados vazios ou errados. - Repetir um
POSTàs cegas. Isso pode criar um segundo pedido ou pagamento; use uma chave de idempotência se a API oferecer. - Escrever a chave direto no código. Ela se espalha por repositórios, capturas de tela e mensagens de chat.
- Insistir diante de um 429. Novas tentativas imediatas mantêm você acima do limite; espere o horário de reinício.
- Ler a documentação errada. Campos e limites mudam entre versões; leia a documentação da versão que você chama.
Guia de decisão
| O que você precisa | O que fazer |
|---|---|
| Testar uma API pela primeira vez | curl -i contra uma API pública de testes |
| Deixar usuários conectarem a conta | OAuth, com o mínimo de scopes |
| Saber de eventos na hora | Um webhook em vez de consultas periódicas |
| Ficar dentro dos limites | Leia os cabeçalhos de limite de taxa |
| Chamar uma API com lista de IPs permitidos | Registre um IP fixo |
| Guardar uma chave | Variável de ambiente ou gerenciador de segredos |
Perguntas frequentes
O que significa API?
API é a sigla de application programming interface (interface de programação de aplicações): o conjunto de requisições que um programa oferece a outros, com as regras sobre o que cada requisição deve conter e o que ela retorna. Na web, a palavra costuma indicar uma API HTTP que responde em JSON.
O que é uma chamada de API?
Uma chamada de API é uma única requisição que um programa envia a uma API, junto com a sua resposta. GET /todos/1, por exemplo, pede um registro, e o servidor responde com um código de status como 200 OK e o registro em JSON. APIs pagas costumam cobrar por chamada.
O que é um endpoint de API?
Um endpoint é o endereço de uma operação, formado pela URL base da API e um caminho, como https://api.example.com/v1/orders. O mesmo caminho pode fazer coisas diferentes conforme o método: GET lista os pedidos e POST cria um.
Usar uma API é de graça?
Depende do provedor. Algumas APIs não pedem chave nenhuma, muitas são gratuitas até uma cota e depois cobram por chamada, e algumas só estão abertas a clientes ou parceiros. O preço, os limites e o que você pode fazer com os dados estão nas páginas do próprio provedor.
O que é um API gateway?
Um API gateway (gateway de API) é um servidor posicionado na frente de uma ou mais APIs que cuida primeiro das tarefas comuns: verificar chaves, aplicar limites de taxa, encaminhar cada caminho ao serviço certo e registrar a atividade. Quem chama vê um único endereço, com muitos serviços por trás.
Preciso saber programar para usar uma API?
Para testar uma, não. Você pode chamar uma API pública com o curl ou pelo painel de testes de um site de documentação, e ferramentas de automação sem código conectam APIs por meio de formulários. Integrar uma API ao seu próprio produto exige código, muitas vezes só algumas dezenas de linhas.
Em resumo
Uma API é um conjunto fixo de requisições que um programa pode enviar a outro: um método e um endpoint saem com uma chave ou um token, e voltam um código de status e dados, normalmente em JSON. REST é o estilo mais comum; GraphQL, gRPC e webhooks cobrem consultas flexíveis, serviços internos e avisos de eventos. Mantenha as chaves fora do código e das URLs, leia o código de status antes dos dados e, quando uma API só aceitar chamadas de endereços registrados, dê a ela um IP fixo em que confiar.




