Contratos de API: Suas Especificacoes de API, Vinculadas a Sua Arquitetura

Algumas semanas atras, eu estava revisando uma arquitetura de sistema com uma equipe que tinha um diagrama C4 lindo. Os containers estavam bem definidos. Os relacionamentos tinham rotulos claros. Tudo parecia otimo — ate alguem perguntar "como e a API entre o Servico de Pedidos e o Gateway de Pagamento?"

Silencio. O diagrama dizia "REST/JSON." A especificacao OpenAPI vivia em outro repositorio. A lista real de endpoints estava em uma pagina do Notion que nao era atualizada desde que o ultimo estagiario saiu. Tres fontes de verdade para uma superficie de API, e nenhuma delas concordava.

Isso e absurdamente comum. Especificacoes de API sao alguns dos artefatos mais precisos e legiveis por maquina em um codebase. No entanto, na documentacao de arquitetura, sao invisiveis. Voce tem uma caixa, uma seta e um rotulo de protocolo. O contrato real — os endpoints, os schemas, os campos — vive em outro lugar completamente.

Construimos Contratos de API para corrigir isso. Suas especificacoes de API agora vivem dentro da sua arquitetura, vinculadas aos elementos que as implementam e consomem.

Quatro Protocolos, Um Lar

Sistemas modernos raramente falam um unico protocolo. Sua API publica e REST, seus servicos internos se comunicam via gRPC e seu frontend busca dados atraves de GraphQL. Cada um tem seu proprio formato de especificacao, suas proprias ferramentas, seu proprio ecossistema de documentacao.

Os Contratos de API do Archyl suportam todos os quatro:

OpenAPI / Swagger — Importe suas especificacoes OpenAPI 3.x ou Swagger 2.0 e obtenha um visualizador de referencia interativo alimentado pelo Scalar. Endpoints sao agrupados, parametros sao documentados, schemas sao expandiveis. E a mesma experiencia que voce teria com uma ferramenta dedicada de documentacao de API, incorporada diretamente no seu workspace de arquitetura.

gRPC / Protocol Buffers — Cole ou sincronize suas definicoes .proto. O visualizador renderiza servicos, metodos, tipos de mensagem e enums com destaque de sintaxe e indentacao adequada. Chega de procurar em arquivos proto para entender o que um servico expoe.

GraphQL — Importe seu schema e explore tipos, queries, mutations e subscriptions. E se voce configurou endpoints de servidor, obtem um playground GraphiQL completo — escreva queries, execute-as contra sua API real e explore o schema interativamente, tudo sem sair do Archyl.

AsyncAPI — Defina suas APIs orientadas a eventos com especificacoes AsyncAPI. O visualizador renderiza canais, operacoes, schemas de mensagens e bindings de servidor com destaque de sintaxe completo. Seja usando Kafka, RabbitMQ, NATS ou WebSockets, contratos AsyncAPI documentam quais eventos seus servicos produzem e consomem.

Importar do Git ou Colar Diretamente

Especificacoes de API mudam. Um endpoint e adicionado, um campo e descontinuado, uma nova versao e lancada. Se sua documentacao requer copiar e colar manualmente para se manter atualizada, ela nao vai se manter atualizada.

Por isso os Contratos de API suportam dois modos de origem:

Sincronizacao Git conecta seu contrato a um arquivo de especificacao em um repositorio. Aponte para seu openapi.yaml, seu service.proto, seu schema.graphql ou seu asyncapi.yaml, e o Archyl busca o conteudo diretamente. Quando a especificacao muda na origem, clique em sincronizar e o contrato se atualiza. Isso funciona com todos os provedores git que o Archyl suporta — GitHub, GitLab, Bitbucket, Azure DevOps e instancias auto-hospedadas.

Manual e para equipes que nao mantem especificacoes no git, ou para prototipagem rapida. Cole o conteudo da especificacao diretamente e edite no local. Util para rascunhar um contrato antes do servico existir, ou para importar uma especificacao de uma API de terceiros que voce nao controla.

Ambos os modos suportam versionamento, para que voce possa rastrear qual versao do contrato esta documentando.

Vinculado a Sua Arquitetura

Aqui e onde os Contratos de API se tornam mais do que um visualizador de especificacoes.

Cada contrato pode ser vinculado a um ou mais elementos C4 — sistemas, containers, componentes ou elementos de codigo. Uma especificacao OpenAPI pode ser vinculada ao container API Gateway que a serve. Um proto gRPC pode ser vinculado ao componente de microsservico que o implementa. Um schema GraphQL pode ser vinculado ao BFF (Backend for Frontend) que o expoe.

Esses vinculos sao bidirecionais. A partir do contrato, voce ve quais elementos de arquitetura ele se relaciona. A partir do painel de detalhes do elemento no diagrama, voce ve quais contratos descrevem sua superficie de API. Quando voce clica com o botao direito em um container no canvas, pode vincular e desvincular contratos diretamente do menu de contexto.

Isso fecha a lacuna que descrevi no inicio. Quando alguem pergunta "como e a API entre esses dois servicos?", a resposta esta a um clique de distancia. Nao em uma ferramenta diferente, nao em um repo diferente — ali mesmo no diagrama.

Canais de Eventos

Arquiteturas orientadas a eventos sao notoriamente dificeis de documentar. Qual servico publica em qual topico? Qual e o schema da mensagem? Quem consome?

Os Canais de Eventos do Archyl trazem visibilidade para sua comunicacao assincrona. Cada contrato AsyncAPI automaticamente expoe os canais que define — topicos, filas, streams — e os mapeia para os elementos C4 que produzem e consomem eventos.

No diagrama, canais de eventos aparecem como tipos de conexao distintos, tornando imediatamente claro quais relacionamentos sao chamadas de API sincronas e quais sao fluxos de eventos assincronos. Isso e critico para entender o comportamento do sistema: uma chamada REST entre dois servicos tem caracteristicas de confiabilidade e acoplamento muito diferentes de um evento publicado em um message broker.

Voce tambem pode criar canais de eventos independentemente dos contratos AsyncAPI, util para documentar sistemas de mensageria legados ou protocolos proprietarios que nao tem uma especificacao formal.

Visualizadores Interativos

Nao queriamos que contratos fossem blocos de texto bruto. Cada protocolo recebe um visualizador construido especificamente:

O visualizador OpenAPI renderiza uma referencia de API totalmente interativa. Endpoints sao organizados por tag, com schemas de requisicao/resposta expandiveis, documentacao de parametros e detalhes de autenticacao. Se voce definiu URLs de servidor, o visualizador as mostra para que desenvolvedores saibam para onde enviar requisicoes. E uma experiencia real de documentacao de API, nao apenas um YAML com destaque de sintaxe.

O visualizador de Protocol Buffer renderiza definicoes proto com coloracao de sintaxe adequada, tornando servicos, RPCs e estruturas de mensagens faceis de escanear.

O visualizador GraphQL destaca tipos, campos e diretivas. E quando voce configurou um endpoint de servidor, uma segunda aba abre um playground GraphiQL completo. Voce pode escrever e executar queries contra sua API ao vivo, explorar o schema atraves de introspeccao e testar mutations — tudo incorporado no Archyl. Se sua API GraphQL tem multiplos ambientes (staging, producao), voce pode definir multiplas entradas de servidor e alternar entre eles.

O visualizador AsyncAPI renderiza suas definicoes de API orientada a eventos com listagens de canais, schemas de mensagens e configuracoes de servidor/broker. Cada canal mostra suas operacoes (publicar/inscrever), schemas de payload e bindings — dando aos desenvolvedores uma imagem clara da sua superficie de comunicacao orientada a eventos.

Como Comecar

Navegue ate qualquer projeto e abra a secao Contratos de API na barra lateral. Clique em "Adicionar Contrato" e escolha seu tipo de protocolo e modo de origem.

Para contratos originados do git, conecte um repositorio (ou reutilize um ja conectado ao seu projeto), especifique o caminho do arquivo e a branch, e o Archyl busca a especificacao. Para contratos manuais, cole o conteudo diretamente.

Uma vez criado, va ao diagrama e vincule o contrato aos elementos C4 relevantes. A partir desse ponto, qualquer pessoa explorando a arquitetura pode acessar a superficie real da API diretamente do diagrama.

Por Que Isso Importa

Diagramas de arquitetura sao poderosos para mostrar estrutura — o que existe e como as coisas se conectam. Mas sempre foram fracos em interfaces. Uma seta de relacionamento rotulada como "REST/HTTPS" diz quase nada sobre o que realmente flui entre dois servicos. Um evento publicado em um topico Kafka e ainda mais opaco — a menos que voce tenha a especificacao AsyncAPI e o mapeamento de canais bem ali.

Contratos de API preenchem essa lacuna. Eles adicionam precisao as setas. Quando um novo membro da equipe olha sua arquitetura e ve uma conexao entre o App Movel e o API Gateway, ele pode imediatamente abrir a especificacao OpenAPI e entender exatamente quais endpoints estao disponiveis, quais estruturas de dados sao trocadas e qual autenticacao e necessaria.

Esta e documentacao de arquitetura que justifica sua existencia. Nao porque alguem a mandou fazer, mas porque responde perguntas reais que surgem todos os dias.

Ja usa o Archyl para sua arquitetura? Explore o recurso de Contratos de API no seu projeto. Novo na plataforma? Aprenda sobre o modelo C4 e como a descoberta com IA pode gerar seu diagrama de arquitetura automaticamente.