APIs bem projetadas: contratos antes de código
Projetar uma API é escrever um contrato entre times, produtos e empresas. O código pode ser refeito; o contrato, uma vez publicado e integrado, muda com custo e negociação. Por isso vale investir tempo no formato antes de investir tempo na implementação.
Comece pelo consumidor, não pelo banco
Uma API que espelha tabelas obriga cada cliente a reconstruir a regra de negócio por conta própria. Uma API que expõe operações significativas do domínio reduz acoplamento e evita que a mesma lógica seja reimplementada em cinco lugares diferentes.
Um exercício simples ajuda: escreva primeiro o exemplo de chamada e de resposta que você gostaria de ler na documentação. Se o exemplo é confuso, o desenho ainda não está pronto.
- Nomes estáveis e previsíveis, no mesmo idioma em toda a superfície.
- Erros com código, mensagem legível e identificador de correlação.
- Paginação, ordenação e filtros definidos desde a primeira versão.
Erros e idempotência são parte do produto
Rede falha, cliente repete, timeout acontece. Operações de escrita precisam de chave de idempotência para que uma repetição não gere duas cobranças ou dois pedidos. Esse detalhe evita a maioria dos incidentes de integração.
Respostas de erro merecem o mesmo cuidado das de sucesso: previsíveis, documentadas e sem vazar informação interna.
Versionar é planejar a mudança
Adicionar campo é seguro; remover ou mudar significado, não. Quando a quebra é inevitável, publique uma nova versão, mantenha a anterior por prazo anunciado e ofereça caminho de migração. Uma política de depreciação escrita vale mais do que qualquer promessa verbal.
Documentação viva e limites explícitos
Especificação gerada a partir do código, exemplos executáveis e ambiente de teste reduzem drasticamente o custo de integração. Limites de uso, cotas e regras de autenticação devem estar na primeira página, não em uma nota de rodapé.
Em resumo
API boa é aquela que alguém integra sem abrir um chamado: contrato claro, erros previsíveis, idempotência e política de versão publicada.
Casos de uso
Integração com ERP de cliente
Contrato estável, chave por parceiro e reprocessamento seguro de eventos duplicados.
Webhook para sistemas externos
Assinatura verificada, reentrega com espera progressiva e registro de cada tentativa.
Aplicativo móvel
Respostas enxutas, versionamento tolerante e compatibilidade com versões antigas ainda instaladas.
Erros comuns
- Expor o modelo de banco diretamente na resposta.
- Retornar sucesso com mensagem de erro dentro do corpo.
- Quebrar contrato sem aviso e sem versão nova.
- Documentar apenas o caminho feliz.
Boas práticas
- Contrato definido e revisado antes da implementação.
- Chave de idempotência em toda operação de escrita relevante.
- Limites de uso e autenticação claros por consumidor.
- Testes de contrato executados no pipeline.
Livros recomendados
Building Microservices — Sam Newman
Trata integração, contratos e limites de serviço com foco prático.
Domain-Driven Design — Eric Evans
Fundamenta como expor operações do domínio em vez de estruturas internas.
Release It! — Michael Nygard
Mostra padrões de resiliência indispensáveis em integração real.
Para aprofundar
Perguntas frequentes
- REST ou GraphQL?
- Depende do consumo. REST tende a ser mais simples de operar e cachear; GraphQL ajuda quando clientes muito diferentes precisam de recortes distintos dos mesmos dados.
- Quando criar a versão 2?
- Quando uma mudança quebra clientes existentes. Adição de campo opcional normalmente não exige nova versão.
- O que é idempotência?
- A garantia de que repetir a mesma chamada produz o mesmo efeito, evitando duplicidade em caso de falha de rede.
- Como documentar sem virar trabalho manual eterno?
- Gerando a especificação a partir do código e validando exemplos no pipeline, para que a documentação não descole da realidade.
Referências
- Roy Fielding — dissertação que origina o estilo REST
- OpenAPI Specification
- Sam Newman — contratos e acoplamento entre serviços
Conteúdo original da equipe i9 Conecty. Conceitos clássicos são explicados com palavras próprias e creditados aos seus autores.