Blog/Artigos · Engenharia
A API como contrato, REST e o modelo de maturidade, GraphQL e gRPC, e o versionamento que não quebra quem depende de você.
A Torá distingue como Deus falava com Moshe do modo como falava com outros profetas: com Moshe era boca a boca, claramente, e não por enigmas. A diferença é entre a comunicação direta e sem ambiguidade e a mensagem cifrada que exige adivinhação. Uma API é uma forma de comunicação entre sistemas, e ela pode ser das duas maneiras. A API mal desenhada fala por enigmas: nomes obscuros, comportamento surpreendente, documentação que não bate com a realidade, e quem consome passa o dia adivinhando o que ela quis dizer. A API bem desenhada fala boca a boca: o contrato é claro, o comportamento é previsível, e quem integra entende sem adivinhar. Desenhar API é, antes de tudo, o compromisso de falar claramente com quem vai depender de você.
O que torna o design de API diferente do design interno é a plateia: uma API tem consumidores que você não controla e que passam a depender dela. Cada campo que você expõe, cada comportamento, cada código de erro, vira uma promessa da qual alguém vai depender, e quebrar essa promessa quebra a integração de quem confiou. Isso muda tudo. Internamente, você refatora à vontade; na API pública, cada mudança carrega o peso de possivelmente quebrar consumidores que você nem sabe que existem. A API é um contrato, e contrato bom é claro na assinatura e estável no cumprimento.
Por isso o bom design de API começa pela perspectiva de quem consome, não de quem implementa. A pergunta certa não é como exponho minha estrutura interna, é o que faz sentido para quem vai usar isto. Nomes que refletem o domínio e não a tabela interna; comportamento previsível que segue o princípio do menor espanto; erros que explicam o que deu errado e o que fazer; consistência para que, aprendida uma parte, o resto seja adivinhável no bom sentido. Falar boca a boca com quem consome é desenhar a API para ser entendida sem que o consumidor precise ler o seu código-fonte para descobrir o que ela realmente faz.
| Aspecto | API por enigmas | API boca a boca |
|---|---|---|
| Nomes | refletem a tabela interna, obscuros | refletem o domínio, óbvios para quem usa |
| Erros | código genérico, sem explicação | dizem o que deu errado e o que fazer |
| Comportamento | surpreende, casos especiais escondidos | previsível, segue o menor espanto |
| Documentação | desatualizada, não bate com a real | contrato explícito, gerado da fonte da verdade |
| Estabilidade | muda e quebra quem depende | evolui sem quebrar o contrato prometido |
REST, o estilo que Roy Fielding descreveu, organiza a API em torno de recursos, substantivos do domínio, endereçados por URL, e manipulados pelos verbos do HTTP: GET para ler, POST para criar, PUT e PATCH para atualizar, DELETE para remover. Bem feito, é intuitivo: quem conhece HTTP adivinha metade da API. O modelo de maturidade de Richardson descreve os degraus de fazer REST de verdade, do nível zero, que só usa HTTP como túnel para chamadas, até usar recursos, usar os verbos com sua semântica correta, e por fim os hyperlinks que guiam o cliente pelo que é possível fazer a seguir.
A maioria das APIs REST do mercado vive nos degraus intermediários, e tudo bem, o pragmatismo vence a pureza. O que importa é usar a semântica do HTTP a favor da clareza, não contra: um GET não deve ter efeito colateral, um DELETE deve ser idempotente, os códigos de status devem significar o que significam, 404 para não encontrado, 400 para pedido malformado, 409 para conflito, e não um 200 com uma mensagem de erro escondida no corpo. Essa coerência é o que faz a API falar boca a boca com toda a infraestrutura de rede, caches, proxies e clientes, que já entendem HTTP. REST bem feito não inventa uma linguagem; usa bem a que já existe e todo mundo fala.
REST é o padrão, mas não é a única boa conversa. O GraphQL, criado no Facebook, inverte quem decide o formato da resposta: em vez de o servidor definir endpoints fixos, o cliente pede exatamente os campos de que precisa, numa única consulta que pode atravessar várias entidades. Isso resolve dois problemas clássicos de REST, o over-fetching, receber mais dados do que precisa, e o under-fetching, ter que fazer várias chamadas para montar uma tela. É poderoso para frontends ricos com necessidades variadas, e por isso casa bem com microfrontends e apps móveis, ao custo de mais complexidade no servidor e desafios próprios de cache e de limitar consultas caras.
O gRPC, do Google, resolve outra necessidade: comunicação de alto desempenho entre serviços. Ele é contract-first por natureza, o contrato é definido primeiro num arquivo de esquema, e usa um formato binário compacto sobre HTTP/2, muito mais eficiente que JSON para tráfego intenso serviço a serviço. É ideal para a comunicação interna de um sistema de microsserviços, onde a performance importa e ambos os lados são seus, e menos adequado para APIs públicas voltadas ao navegador. A escolha entre os três não é de moda, é de adequação: REST para APIs de recurso claras e públicas, GraphQL para clientes com necessidades variadas de leitura, gRPC para comunicação interna de alta performance. Muitas arquiteturas usam os três, cada um onde fala melhor.
| Estilo | Quem decide o formato | Onde brilha | O custo |
|---|---|---|---|
| REST | o servidor, em endpoints | APIs de recurso claras e públicas | over e under-fetching |
| GraphQL | o cliente, pedindo campos | frontends ricos, apps, microfrontends | complexidade de servidor, cache, consultas caras |
| gRPC | contrato binário, definido antes | comunicação interna de alta performance | menos amigável ao navegador |
Falar boca a boca exige que o contrato exista antes e explicitamente, e é isso que o design contract-first propõe: definir o contrato da API, com OpenAPI para REST, esquema para GraphQL, protobuf para gRPC, antes de implementar, e gerar a partir dele a documentação, os stubs de cliente e servidor, e os testes de contrato. O ganho é que o contrato vira a fonte única da verdade, negociada entre quem serve e quem consome antes de uma linha de código, e a documentação nunca mais fica desatualizada, porque ela é gerada do contrato, não escrita à parte e esquecida.
E há o problema que separa a API amadora da profissional: a evolução. Uma API viva precisa mudar, mas mudar sem quebrar quem depende dela. A regra de ouro é a compatibilidade retroativa: adicionar campos e endpoints é seguro, porque quem não os usa não é afetado; remover ou mudar o significado de algo é uma mudança que quebra, e essas exigem versionamento explícito e um período em que a versão antiga convive com a nova, dando tempo aos consumidores de migrar. Quebrar o contrato sem aviso é o pior pecado de uma API, porque a confiança que o consumidor depositou nela é justamente o que a torna útil, e uma API em que não se pode confiar para não quebrar é uma API que ninguém quer integrar. Falar boca a boca inclui não mudar de língua sem avisar quem aprendeu a sua.
O design de API amadurece do enigma ao contrato tratado como produto. No começo a API é um reflexo da estrutura interna, fala por enigmas, muda sem aviso. Depois vem o uso coerente da semântica, REST bem feito. No meio vem o contract-first, com o contrato como fonte da verdade e documentação gerada. No topo é a API tratada como produto: desenhada para o consumidor, versionada com compatibilidade retroativa, com o estilo certo, REST, GraphQL ou gRPC, para cada necessidade, e a evolução governada para nunca quebrar quem confiou. Cada degrau troca a conveniência de quem implementa pela clareza de quem consome.
A API é a costura de tudo o que este eixo construiu. É por ela que os microsserviços conversam, e um contrato ruim recria o acoplamento que a divisão queria evitar; é o contrato que a arquitetura de eventos publica; é a fronteira do contexto delimitado do DDD exposta ao mundo; e é a porta do hexágono da Clean Architecture voltada para fora. Falar boca a boca, claramente e não por enigmas, é o compromisso que torna todas essas peças integráveis, porque de nada adianta um sistema bem arquitetado por dentro se ele fala por enigmas com quem precisa consumi-lo. A clareza do contrato é a cortesia que a engenharia deve a quem depende dela, e é ela que faz um sistema ser não só correto, mas usável por outros.
Design de API é o compromisso de falar boca a boca, claramente e não por enigmas, com quem vai depender de você. A API é um contrato, e cada campo exposto é uma promessa: desenhe pela ótica do consumidor, use a semântica do HTTP a favor da clareza, e escolha REST, GraphQL ou gRPC por adequação, não por moda. A regra de ouro da evolução é a compatibilidade retroativa, para nunca quebrar quem confiou. A IA é o consumidor exigente e o guardião do contrato. Mas a cortesia de falar claramente com quem depende de você continua sendo uma escolha de quem entende que sistema correto por dentro precisa ser usável por fora.
Gerente de Operações, Tecnologia e Infraestrutura (SRE) numa central de registros. Trabalho com tecnologia desde 2009 e com cibersegurança em tempo integral desde 2015, em infraestrutura crítica, fintech e banking. Escrevo sobre o que eu opero: confiabilidade, segurança, governança e IA que passa por gate antes de chegar em produção.
Engenhariaסֵפֶר זִכָּרוֹן
Em vez de um serviço mandar no outro, cada um anuncia o que aconteceu, e quem se interessa reage. O evento é um fato registrado, como um livro de memória, e daí nascem o desacoplamento, o CQRS e o event sourcing, com o preço da consistência eventual e da depuração difícil.
Engenhariaתּוֹרָה אַחַת
Sem padrão, cada time reinventa o botão, e o produto vira uma babel visual. Design system é uma só lei para toda a interface: tokens e componentes reutilizáveis, montados dos átomos às páginas, numa fonte única da verdade que dá consistência, acessibilidade e velocidade de uma vez.
