Contratos de API - Archyl Docs

Documente e gerencie especificações de API vinculadas diretamente aos seus elementos de arquitetura C4

Contratos de API

Os Contratos de API permitem anexar especificações de API aos seus elementos de arquitetura, mantendo documentação e design sincronizados. O Archyl suporta contratos OpenAPI (REST), gRPC, GraphQL, AsyncAPI e MCP, com sincronização opcional via git ou descoberta ao vivo.

Tipos de Contrato Suportados

Tipo Formato Caso de Uso
HTTP (REST) OpenAPI 3.x (YAML/JSON) APIs REST, webhooks
gRPC Protocol Buffers (.proto) RPC entre serviços
GraphQL GraphQL SDL (.graphql) APIs de consulta
Async AsyncAPI (YAML/JSON) APIs orientadas a eventos, filas de mensagens
MCP MCP tools/list (JSON) Tools expostos a agentes de IA

Criando um Contrato

Entrada Manual

  1. Navegue até seu projeto
  2. Abra a aba Contratos de API
  3. Clique em Novo Contrato
  4. Preencha os detalhes do contrato:
    • Nome — Um nome descritivo (ex.: "API do User Service")
    • Tipo — HTTP, gRPC, GraphQL, Async ou MCP
    • Versão — Versão semântica (ex.: 1.0.0)
    • Endpoint — URL base da API
    • Descrição — O que a API faz
  5. Cole ou escreva o conteúdo da especificação no editor
  6. Clique em Criar

Sincronização via Git

Em vez de manter contratos manualmente, você pode sincronizá-los a partir de um repositório git:

  1. Clique em Novo Contrato e selecione Git como tipo de fonte
  2. Escolha um repositório conectado
  3. Especifique o caminho do arquivo de especificação (ex.: api/openapi.yaml)
  4. Defina o branch a rastrear (padrão é o branch padrão do repositório)
  5. O Archyl puxa o conteúdo da especificação e o mantém sincronizado

Você também pode usar padrões glob para corresponder a múltiplos arquivos. Por exemplo, api/**/*.yaml corresponderá a todos os arquivos YAML no diretório api/.

Comportamento da Sincronização

  • As especificações são buscadas do repositório quando o contrato é criado
  • Use o botão Sincronizar para puxar manualmente a versão mais recente
  • O timestamp da última sincronização é exibido no cartão do contrato

Servidores MCP

Os servidores MCP (Model Context Protocol) expõem tools a agentes de IA — cada um com um nome, uma descrição e um JSON Schema para suas entradas. Essa superfície de tools também é um contrato: ela define o que um agente tem permissão para fazer. O Archyl a documenta como o tipo de contrato MCP.

Diferente dos outros tipos, os tools de um servidor MCP geralmente não são um arquivo em um repositório — a lista autoritativa só existe em tempo de execução, via a chamada tools/list. Por isso os contratos MCP suportam duas fontes.

Colar a lista de tools

  1. Clique em Novo Contrato e escolha MCP
  2. Mantenha a fonte como Manual
  3. Cole o JSON tools/list do servidor — um objeto da forma { "tools": [ ... ] }
  4. Clique em Criar

O Archyl valida o documento e renderiza cada tool.

Descobrir a partir de um endpoint ao vivo

Deixe o Archyl buscar os tools diretamente de um servidor em execução:

  1. Clique em Novo Contrato, escolha MCP e selecione Live endpoint como fonte
  2. Insira a URL do servidor e escolha o transporte (HTTP ou SSE)
  3. Se o servidor exigir autenticação, escolha onde o token vai — um cabeçalho (ex.: X-API-Key) ou um parâmetro de URL — e insira o token
  4. Clique em Descobrir tools — o Archyl conecta, executa o handshake e lista cada tool e seus parâmetros
  5. Revise os tools descobertos e clique em Criar

Para atualizar os tools depois, edite o contrato e execute Descobrir tools novamente.

A descoberta roda no seu navegador, não nos servidores do Archyl. Seu token nunca sai do seu navegador — o Archyl armazena os tools descobertos e os detalhes de conexão (URL, transporte, nome do cabeçalho/parâmetro) mas nunca o token em si. Como a chamada se origina na sua máquina, ela também pode alcançar servidores em localhost ou na sua rede privada.

O único requisito: o servidor MCP precisa permitir a origem deste site (CORS) para que seu navegador possa ler a resposta. Para servidores que você controla, é uma pequena mudança de configuração; caso contrário, use a opção de colar acima.

O visualizador de tools MCP

Cada tool é mostrado com seu nome, descrição e parâmetros de entrada (derivados do seu JSON Schema), com o schema bruto disponível por tool. Como os outros tipos de contrato, o visualizador é somente leitura e reflete a lista de tools armazenada.

Vinculando Contratos à Arquitetura

Os contratos de API se tornam significativos quando vinculados aos elementos C4 que eles descrevem. Um contrato pode ser vinculado a sistemas, containers, componentes ou elementos de código.

Adicionando Vínculos

  1. Abra a página de detalhes de um contrato
  2. Clique em Vincular a Elemento
  3. Selecione o nível C4 (Sistema, Container, Componente ou Código)
  4. Escolha o elemento de destino
  5. O vínculo aparece tanto no contrato quanto no painel de detalhes do elemento

Visualizando Contratos Vinculados

No diagrama, clique com o botão direito em qualquer elemento para abrir seu painel de detalhes. Os contratos de API vinculados aparecem na seção Contratos com:

  • Nome e versão do contrato
  • Badge do tipo de protocolo (HTTP, gRPC, GraphQL, Async, MCP)
  • Link para a especificação completa

Entradas de Servidor

Cada contrato pode definir múltiplas entradas de servidor — útil para documentar diferentes ambientes ou regiões.

Campo Descrição
URL A URL base do servidor (ex.: https://api.example.com/v1)
Descrição Ambiente ou propósito (ex.: "Produção", "Staging")

O Visualizador de Especificações

O Archyl renderiza suas especificações de API com um visualizador interativo:

  • OpenAPI — Endpoints agrupados por tag, com schemas de requisição/resposta, parâmetros e exemplos
  • gRPC — Definições de serviço, métodos RPC e tipos de mensagem
  • GraphQL — Tipos, queries, mutations e subscriptions
  • AsyncAPI — Canais, mensagens e schemas
  • MCP — Tools, cada um com sua descrição e parâmetros de entrada (do seu JSON Schema)

O visualizador é somente leitura e sempre reflete o conteúdo atual do contrato.

Canais de Eventos

Os canais de eventos documentam o lado de mensageria assíncrona da sua arquitetura — tópicos Kafka, filas SQS, exchanges RabbitMQ e similares.

Criando um Canal de Eventos

  1. Navegue até seu projeto
  2. Abra a aba Canais de Eventos
  3. Clique em Novo Canal
  4. Configure o canal:
Campo Descrição
Nome Nome do canal (ex.: "Eventos de Pedido Criado")
Direção produce ou consume
Tipo de Broker Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar ou Personalizado
Nome do Tópico O nome real do tópico ou fila
Formato do Schema JSON Schema, Avro, Protobuf ou Texto
Schema de Valor A definição do schema do payload do evento

Vinculando à Arquitetura

Os canais de eventos seguem o mesmo modelo de vinculação dos contratos de API. Vincule um canal aos sistemas, containers ou componentes que produzem ou consomem seus eventos. Isso torna os fluxos de mensagens visíveis diretamente no diagrama de arquitetura.

Boas Práticas

Mantenha as Especificações Atualizadas

  • Use sincronização via git para especificações que vivem no código
  • Versione seus contratos seguindo versionamento semântico
  • Atualize o contrato quando a API mudar

Vincule Tudo

  • Todo container que serve uma API deve ter pelo menos um contrato vinculado
  • Vincule canais de eventos tanto a produtores quanto a consumidores
  • Use vínculos para tornar o diagrama autodocumentado

Organize por Serviço

  • Um contrato por serviço ou contexto delimitado
  • Use nomes descritivos que correspondam à nomenclatura da sua arquitetura
  • Inclua a versão da API no campo de versão do contrato

Documente os Servidores

  • Adicione entradas de servidor para cada ambiente
  • Inclua endpoints internos e externos
  • Mantenha as URLs atualizadas conforme a infraestrutura muda

Próximos Passos