Escolher o formato da integração olhando quem vai consumir

Escolher REST, GraphQL ou tRPC sem perguntar quem consome a API custa retrabalho quando o parceiro externo não consegue integrar sozinho. A pergunta que encerra o assunto é simples: quem vai consumir essa API, gente de dentro ou de fora da empresa.

REST organiza a conversa em endereços e verbos, viaja pelo protocolo da web e é a opção que qualquer linguagem consome sem ferramenta especial. GraphQL deixa o cliente pedir exatamente os campos que quer, numa consulta só, e rende quando muitas telas diferentes bebem da mesma fonte.

tRPC dispensa contrato escrito porque o compilador infere os tipos das duas pontas, e só funciona com TypeScript nos dois lados, publicados juntos.

A fronteira que decide é a da empresa. Contrato que sai dela precisa existir fora da linguagem de quem escreveu, num arquivo que o outro lado lê, versiona e testa.

Na Distribuidora Aurora, cenário ilustrativo do curso, o portal de pedidos conversa com o sistema de gestão da casa e com dois transportadores. O sistema de gestão fica dentro da fronteira, e os transportadores ficam fora: só a segunda conversa precisa de contrato publicado.

Esse arquivo tem nome e versão: OpenAPI 3.2.0, publicada em setembro de 2025. Documento escrito na versão anterior continua válido, o que evita reescrita por moda.

Dentro da mesma fronteira a conta se inverte. Quando as duas pontas sobem no mesmo momento e quebram juntas, a inferência do compilador já serve de contrato e sai mais barata. Por isso a resposta madura costuma ser duas superfícies a partir do mesmo núcleo: uma publicada para terceiros, outra inferida para o time de casa.

Integração que atravessa a fronteira da empresa exige contrato publicado, e ele só vale como tal quando o parceiro consegue gerar o cliente dele sozinho. Peça o arquivo antes de anunciar a integração, confirme a versão do formato, hoje OpenAPI 3.2.0, e exija exemplo de chamada e de erro em cada endereço.

Combine também quem avisa o parceiro quando algo muda. Esse arquivo publicado dá três coisas ao outro lado.

A primeira é gerar o cliente na linguagem dele sem montar chamada na mão. A segunda é subir um servidor falso a partir do arquivo para começar a integrar antes de a implementação final existir.

Terceira vantagem: rodar teste de contrato na esteira, que falha assim que a resposta real deixa de bater com o documento publicado. Separe os consumidores em duas colunas, de dentro e de fora.

Combine a data de publicação do arquivo de contrato antes de anunciar a integração. O parceiro passa a trabalhar contra esse documento, sem esperar a implementação ficar pronta.