API é um termo que atravessou a fronteira do vocabulário técnico e apareceu em reuniões comerciais, propostas de projeto e conversas sobre integração. E, como costuma acontecer nesses casos, ele é usado com muito mais frequência do que é explicado.
O conceito é simples e útil de entender mesmo para quem não vai programar nada: ele esclarece o que significa “integrar dois sistemas”, por que algumas integrações são triviais e outras são caras, e o que muda quando a API é sua em vez de ser de outra pessoa.
Este guia explica o que é uma API, como sistemas conversam entre si, a diferença para webhooks e o que uma API própria exige de infraestrutura.
A definição
API é a sigla, em inglês, para interface de programação de aplicações. Em português simples: é a forma pela qual um sistema oferece funcionalidades e dados para outro sistema usar.
A analogia que costuma funcionar é a do balcão de atendimento. Você não entra na cozinha do restaurante para pegar o prato: existe um balcão, um cardápio com o que pode ser pedido e um procedimento para fazer o pedido. A API é esse balcão — ela define o que pode ser solicitado, como solicitar e em que formato a resposta volta.
Duas consequências dessa definição:
- Você não precisa saber como o outro sistema funciona por dentro. Só precisa conhecer o que ele oferece e como pedir.
- O sistema que oferece a API controla o que expõe. Ele decide quais operações são possíveis e quais dados retorna.
É por isso que APIs tornaram possível o cenário atual, em que ferramentas de fornecedores diferentes conversam entre si sem que ninguém precise abrir o código de ninguém.
Como funciona na prática
A maior parte das APIs usadas na web segue um padrão razoavelmente uniforme:
- Um sistema faz uma requisição para um endereço específico — o *endpoint* — indicando o que quer.
- A requisição inclui uma credencial que identifica quem está pedindo.
- Pode incluir também parâmetros: qual registro, quais filtros, quais dados enviar.
- O sistema que recebe valida a credencial e a permissão para aquela operação.
- Ele processa o pedido e devolve uma resposta, normalmente em um formato estruturado que outro programa consegue interpretar.
- A resposta inclui um código de status que indica se deu certo, se houve erro do solicitante ou falha do servidor.
O passo 6 é o que permite tratar erros automaticamente: quem chama a API sabe distinguir entre “o registro não existe”, “você não tem permissão” e “o sistema falhou” — e reagir de forma diferente a cada caso.
API e webhook: a diferença que confunde
São mecanismos complementares e a distinção é simples, mas ela gera confusão constante.
Em uma chamada de API, o seu sistema pergunta. Ele decide quando quer a informação e vai buscá-la: “tem pedidos novos?”, “qual o status deste pagamento?”.
Em um webhook, o outro sistema avisa. Quando algo acontece, ele envia uma notificação para um endereço que você forneceu: “um pedido acabou de ser criado”, “este pagamento foi confirmado”.
| Chamada de API | Webhook | |
|---|---|---|
| Quem inicia | Seu sistema | O sistema externo |
| Quando acontece | Quando você decide | Quando o evento ocorre |
| Atualidade da informação | Depende da frequência | Imediata |
| Custo de recursos | Cresce com a frequência | Só quando há evento |
| Requisito | Poder chamar o outro sistema | Ter um endereço público disponível |
A última linha é a que tem consequência de infraestrutura: para receber webhooks, é preciso ter um endereço acessível pela internet, ativo o tempo todo. Sistemas que rodam apenas no computador de alguém, ou em ambientes que não expõem endereços públicos, não recebem webhooks.
Consumir uma API é diferente de oferecer uma
Esta distinção reorganiza a conversa sobre custo e complexidade de um projeto.
Consumir uma API de terceiros é o caso mais comum. Você usa um serviço de pagamento, um sistema de frete, uma ferramenta de CRM. A infraestrutura é de quem oferece; você precisa apenas de credenciais e de código que faça as chamadas.
Oferecer uma API significa que outros sistemas — internos, de clientes ou parceiros — vão chamar o seu. E aí a natureza do projeto muda: você passa a ter um serviço que precisa estar disponível quando alguém precisar dele.
A diferença prática mais evidente: quando você consome uma API, a indisponibilidade dela é um problema seu, mas a responsabilidade é de outro. Quando você oferece, a indisponibilidade é responsabilidade sua — e quem depende dela vai perceber.
O que uma API própria exige
Se o seu projeto inclui oferecer uma API, alguns requisitos deixam de ser opcionais:
Ficar sempre disponível
Uma API que responde apenas em horário comercial é uma API que quebra as integrações que dependem dela fora desse horário. Isso significa um serviço em execução permanente, com reinício automático em caso de falha — os requisitos tratados no artigo sobre aplicações Node.js em produção.
Autenticação e controle de acesso
Credenciais individuais por consumidor, com possibilidade de revogar uma sem afetar as demais. Credencial compartilhada entre vários integradores é um problema esperando para acontecer — quando for preciso revogá-la, todos param.
Limite de requisições
Sem um limite por consumidor, uma integração mal construída ou um problema no cliente pode derrubar a sua API para todos os outros. O limite não é hostilidade: é o que garante que um consumidor não afete os demais.
Versionamento
Assim que alguém integra com a sua API, você não pode mais mudar o formato das respostas livremente — isso quebraria a integração deles. Versionar permite evoluir sem quebrar quem já usa.
Documentação
Uma API sem documentação é uma API que gera chamados de suporte. O que precisa estar documentado: quais operações existem, quais parâmetros aceitam, o formato das respostas, os códigos de erro e os limites aplicáveis.
Monitoramento
APIs falham em silêncio, como automações. Se ninguém acompanha taxa de erro e tempo de resposta, o problema aparece pela reclamação de quem integrou.
Segurança: o que muda quando você expõe uma API
Uma API pública é uma porta para o seu sistema, e ela é acessada por programas — não por pessoas navegando.
Os cuidados que fazem mais diferença:
- HTTPS obrigatório. Credenciais trafegando sem criptografia são credenciais vazadas.
- Credenciais fora do código. Um segredo em código versionado é um segredo público — vale para quem oferece e para quem consome.
- Permissões mínimas. Cada credencial deve poder fazer apenas o que aquele integrador precisa.
- Validação de tudo que chega. Nunca confiar que o dado recebido está no formato esperado.
- Registro de acessos, para investigar comportamento anômalo.
- Rotação de credenciais, com procedimento definido para quando uma vaza.
Um cuidado específico de webhooks: como o endereço é público, qualquer um pode enviar dados para ele. É preciso verificar que a chamada veio realmente do serviço esperado — a maior parte das plataformas oferece um mecanismo de assinatura para isso, e ignorá-lo significa aceitar dados de qualquer origem.
Onde uma API roda
A pergunta prática para quem vai colocar uma no ar.
Uma API é uma aplicação que precisa permanecer ativa, escutar em uma porta e responder a qualquer momento. Isso exclui hospedagem compartilhada tradicional, construída para executar código a cada visita e encerrar o processo em seguida.
O requisito é um ambiente que execute serviços permanentes, com recursos reservados e controle de configuração — seja para uma API em Node.js, em Python ou em outra tecnologia.
Sobre dimensionamento, uma observação que vale para qualquer API: o consumo raramente é proporcional ao número de consumidores. Um integrador que consulta a cada minuto gera mais carga que dez que consultam uma vez por dia. É por isso que o limite de requisições é também uma ferramenta de dimensionamento, e não apenas de proteção.
Conclusão
Uma API é a forma pela qual um sistema oferece dados e funcionalidades para outro usar, sem que nenhum precise conhecer o funcionamento interno do outro. É o mecanismo que permite que ferramentas de fornecedores diferentes trabalhem juntas.
A distinção que mais importa na prática é entre consumir e oferecer. Consumir exige credenciais e código. Oferecer transforma o projeto em um serviço que precisa estar disponível, autenticado, limitado, versionado, documentado e monitorado.
Se o seu projeto inclui uma API própria, o requisito de partida é um ambiente que execute serviços permanentes. Conheça o Cloud Server para Node.js da TBF Host e avalie a configuração adequada ao perfil da sua aplicação.
Perguntas frequentes
O que é uma API?
É a forma pela qual um sistema oferece funcionalidades e dados para outro sistema usar. Ela define o que pode ser solicitado, como solicitar e em que formato a resposta volta — sem que quem consome precise conhecer o funcionamento interno de quem oferece. É o mecanismo que permite ferramentas diferentes trabalharem juntas.
Qual a diferença entre API e webhook?
Em uma chamada de API, o seu sistema pergunta quando quer a informação. Em um webhook, o sistema externo avisa quando um evento acontece, enviando uma notificação para um endereço que você forneceu. A diferença prática mais relevante é que receber webhooks exige ter um endereço público acessível o tempo todo.
O que é um endpoint?
É o endereço específico ao qual uma requisição é enviada dentro de uma API. Cada operação disponível costuma ter seu próprio endpoint — um para listar registros, outro para criar, outro para consultar um item específico. A documentação da API é o que informa quais endpoints existem e o que cada um aceita.
Preciso de servidor próprio para ter uma API?
Se a API é sua e precisa responder a qualquer momento, sim. Uma API é uma aplicação que fica permanentemente ativa e escuta em uma porta, o que exclui a hospedagem compartilhada tradicional, construída para executar código a cada visita e encerrar o processo em seguida.
O que é limite de requisições em uma API?
É um teto de chamadas que cada consumidor pode fazer em determinado período. Ele existe para que uma integração mal construída ou um problema em um cliente não derrube a API para todos os outros. Também funciona como ferramenta de dimensionamento, já que o consumo depende da frequência das chamadas.
Como proteger uma API?
Com HTTPS obrigatório, credenciais individuais por consumidor e fora do código, permissões mínimas para cada uma, validação de todos os dados recebidos, registro de acessos e um procedimento definido de rotação de credenciais. Em webhooks, é essencial verificar a assinatura para confirmar que a chamada veio do serviço esperado.
Por que preciso versionar minha API?
Porque, assim que alguém integra com ela, mudar o formato das respostas quebra a integração dessa pessoa. O versionamento permite evoluir a API — adicionar campos, mudar comportamentos — mantendo a versão anterior funcionando para quem ainda não migrou.
Quanto de recurso uma API consome?
Depende muito mais da frequência das chamadas do que do número de consumidores. Um integrador que consulta a cada minuto gera mais carga que dez que consultam uma vez por dia. Também pesa a natureza do trabalho: consultas simples ao banco consomem pouco; processamento de dados ou geração de arquivos consome bastante.