API: o que é, como funciona e o que é uma API REST

O site da loja mostra o estoque atualizado. A cobrança sai com o QR Code do Pix. O lead do formulário aparece no CRM sem ninguém digitar nada. Ninguém na sua empresa escreveu código para isso, e mesmo assim cada uma dessas coisas depende de uma API que alguém publicou e outro sistema consumiu.

A sigla aparece em proposta de fornecedor, em reunião de TI e na tela de configuração de plugin. Quase sempre chega sem explicação, como se todo mundo já soubesse o que é.

Uma interface de programação é um contrato: um sistema publica o que aceita receber e o que promete devolver, e outro sistema faz pedidos dentro dessas regras sem ver o código de dentro. Quando uma integração quebra, o motivo raramente está no código. Quase sempre o contrato mudou sem aviso ou a chave vazou.

O que é uma API, sem jargão

Pense no balcão de um cartório. Você não entra no arquivo nem abre gaveta, e não faz ideia de como os livros estão organizados. Você entrega um pedido preenchido do jeito que o balcão aceita e recebe uma certidão num formato conhecido.

Uma interface de programação faz o mesmo papel entre dois sistemas. O lado que oferece o serviço define os pedidos que aceita, o formato de cada um e o que devolve em cada caso. O lado que consome não precisa saber em que linguagem o outro foi escrito nem qual banco de dados ele usa. Basta seguir o combinado.

A sigla vem do inglês Application Programming Interface. A palavra que carrega o sentido é interface: a parte exposta, enquanto o resto fica fechado. Isso protege os dois lados. O fornecedor pode reescrever o sistema inteiro por dentro e, se mantiver o contrato, ninguém do lado de fora percebe a troca.

Requisição e resposta: o que viaja de um lado para o outro

Quase todas as APIs da web conversam por HTTP, o mesmo protocolo que o navegador usou para abrir esta página. Cada conversa tem duas metades, e a primeira é a requisição. Ela leva quatro partes:

• Método: o verbo, que diz o que se quer fazer com o recurso.
• Endpoint: o endereço do recurso, como https://exemplo.com/v1/pedidos/123.
• Cabeçalho: os metadados do pedido, entre eles a credencial e o formato do conteúdo.
• Corpo: os dados enviados, em geral no formato JSON, quando o método pede conteúdo.

Os métodos têm significado definido pelo próprio HTTP. Segundo a referência de métodos da MDN, o GET pede uma representação do recurso e só deve buscar dados. O POST envia dados e costuma causar mudança no servidor. O PUT substitui o recurso inteiro pelo conteúdo enviado, o PATCH altera só uma parte dele e o DELETE apaga.

A segunda metade é a resposta. Ela volta com um código de status de três dígitos e, quase sempre, um corpo. O primeiro dígito já diz a família: 2xx é sucesso, 4xx é erro de quem pediu e 5xx é erro do servidor. A lista de códigos de status da MDN descreve cada um. Estes são os que mais aparecem em integração:

Saber ler esses números encurta muita conversa com fornecedor. Um 401 manda olhar a credencial antes de qualquer outra coisa. Já um 500 indica falha do lado de lá, e mexer na sua configuração não vai resolver.

O que é uma API REST

REST é um estilo de arquitetura que Roy Fielding descreveu na tese de doutorado dele, publicada em 2000. O capítulo 5 da tese define o estilo por um conjunto de restrições: cliente e servidor separados, comunicação sem estado, cache, interface uniforme e sistema em camadas, mais uma opcional de código sob demanda.

Duas delas explicam quase tudo o que você vê numa integração. A primeira é a ausência de estado. Cada requisição carrega toda a informação necessária para ser entendida, e o servidor não depende da conversa anterior. Por isso a credencial vai em todo pedido, e não só no primeiro.

A segunda é a interface uniforme. Cada recurso tem um identificador próprio e é manipulado pelos mesmos verbos. Por isso /pedidos/123 é o pedido 123, e GET, PUT e DELETE nesse endereço fazem o que o nome diz.

Uma API REST, então, é uma interface que segue essas regras sobre HTTP. Muitas das que se dizem REST seguem só parte delas. Para quem integra, isso raramente faz diferença. Pesa mais a documentação dizer com clareza quais endereços existem e o que cada um devolve.

Três alternativas ao REST aparecem com frequência em proposta técnica.

O SOAP é um protocolo mais antigo e mais formal. Toda mensagem vai num envelope XML, e o contrato fica descrito num arquivo próprio, o WSDL. Ainda é comum em sistemas legados de banco, governo e grandes ERPs.

O GraphQL usa um único endereço. O cliente escreve uma consulta dizendo exatamente quais campos quer, e recebe só aqueles. Isso economiza tráfego em aplicativo e dá mais trabalho no servidor.

O webhook inverte a direção. Em vez de o seu sistema perguntar de tempos em tempos se algo mudou, o outro lado avisa quando o evento acontece. O pagamento confirmado chega até você sem consulta. O post sobre como funcionam os webhooks detalha esse modelo.

Chave de API, OAuth e limite de uso

A forma mais simples de credencial é a chave. Ela é uma sequência longa que vai no cabeçalho de cada pedido. Para o fornecedor, quem apresenta a chave é a sua empresa, com todas as permissões que ela carrega. Chave em código publicado, em planilha compartilhada ou em print de tela tem o mesmo efeito de senha exposta.

O OAuth resolve outro problema. Em vez de entregar uma credencial com acesso total, alguém autoriza um aplicativo a fazer coisas específicas, por tempo limitado. O aplicativo recebe um token com escopo, e esse token pode ser revogado sem trocar a senha de ninguém.

A especificação da API Pix publicada pelo Banco Central mostra isso bem. Ela declara escopos OAuth2 separados para cada operação, como cob.read para consultar cobrança e cob.write para criar ou revisar. Um sistema que só confere pagamentos pode receber apenas o escopo de leitura.

O limite de uso é a outra regra de convivência. O fornecedor decide quantos pedidos aceita por minuto, hora ou dia, em geral conforme o plano. Passou do limite, a resposta vira 429 até a janela reiniciar. Integração que roda em lote no fim do mês costuma descobrir esse limite no pior dia.

Documentação e versão: onde o contrato mora

Se a interface é um contrato, a documentação é o texto dele. Um formato frequente é o OpenAPI, que descreve endpoints, parâmetros, respostas e erros num arquivo que tanto gente quanto ferramenta conseguem ler.

O caso do Pix ajuda de novo. O repositório do Banco Central define a especificação funcional em OpenAPI 3.0, e o arquivo trazia a versão 2.10.0 quando o conferi, em 12 de outubro de 2026. A própria especificação diz seguir versionamento semântico, com o número principal da versão no caminho da URL.

Ela também lista o que considera mudança compatível: novos recursos, novos parâmetros opcionais, novos campos nas respostas, alteração na ordem dos campos e novos valores em enumerações. E avisa que essas mudanças podem ocorrer a qualquer momento, e que os clientes devem estar preparados para lidar com elas sem quebrar.

Esse trecho resume a tese deste post. Se a sua integração para porque apareceu um campo novo na resposta, o defeito está do seu lado. Se o fornecedor removeu um campo sem subir a versão principal, o defeito está do lado dele. Nos dois casos, quem tem a documentação e o histórico de versões resolve a discussão em minutos.

Onde a sua empresa já usa API sem saber

O Pix é o exemplo mais visível. O sistema de cobrança conversa com o banco ou com o provedor de pagamento para gerar a cobrança e consultar se ela foi paga. O emissor de nota fiscal envia o documento para autorização e recebe o retorno, e o ERP faz o mesmo quando emite em lote.

O atendimento automatizado no WhatsApp passa pela interface oficial da Meta, assunto do post sobre automação com a WhatsApp Business API. O formulário do site que cria contato no CRM ou na ferramenta de automação de marketing faz uma chamada a cada envio, como mostra o guia para integrar o Mautic com o site ou o CRM.

Ferramentas de automação como o n8n são, por dentro, uma coleção de chamadas a APIs com uma tela visual por cima. Cada caixinha do fluxo guarda uma credencial de algum sistema da empresa.

O que fazer na sua empresa

1. Faça o inventário. Liste cada API que a empresa consome, o sistema de cada lado, a credencial usada e em nome de quem ela foi criada.
2. Use uma credencial por integração. Chave compartilhada entre três sistemas não pode ser revogada sem derrubar os três.
3. Guarde chave em cofre. Nunca em código, planilha, e-mail ou chat. Troque a chave quando a pessoa que a criou sair da empresa.
4. Peça escopo mínimo. Quando o fornecedor oferece OAuth, autorize só as operações que a integração usa.
5. Coloque a política de versão no contrato comercial. Prazo de aviso antes de mudança incompatível e por quanto tempo a versão antiga continua no ar.
6. Monitore os códigos de status. Alerta para 401, 429 e 5xx avisa do problema antes que o cliente reclame.

O ponto que fica

Uma integração dura enquanto as duas pontas respeitam o mesmo contrato e a credencial continua secreta. A especificação da API Pix deixa a regra escrita para quem quiser ler: mudanças compatíveis podem acontecer a qualquer momento, e quem consome a interface precisa estar pronto para elas.