Contratos de API - Archyl Docs

Documenta y gestiona especificaciones de API vinculadas directamente a los elementos de tu arquitectura C4

Contratos de API

Los Contratos de API te permiten adjuntar especificaciones de API a tus elementos de arquitectura, manteniendo la documentación y el diseño sincronizados. Archyl soporta contratos OpenAPI (REST), gRPC, GraphQL, AsyncAPI y MCP, con sincronización git opcional o descubrimiento en vivo.

Tipos de Contratos Soportados

Tipo Formato Caso de uso
HTTP (REST) OpenAPI 3.x (YAML/JSON) APIs REST, webhooks
gRPC Protocol Buffers (.proto) RPC servicio-a-servicio
GraphQL GraphQL SDL (.graphql) APIs de consulta
Async AsyncAPI (YAML/JSON) APIs basadas en eventos, colas de mensajes
MCP MCP tools/list (JSON) Tools expuestos a agentes de IA

Crear un Contrato

Entrada Manual

  1. Navega a tu proyecto
  2. Abre la pestaña Contratos de API
  3. Haz clic en Nuevo Contrato
  4. Completa los detalles del contrato:
    • Nombre — Un nombre descriptivo (ej. "API del Servicio de Usuarios")
    • Tipo — HTTP, gRPC, GraphQL, Async o MCP
    • Versión — Versión semántica (ej. 1.0.0)
    • Endpoint — URL base de la API
    • Descripción — Qué hace la API
  5. Pega o escribe el contenido de la especificación en el editor
  6. Haz clic en Crear

Sincronización con Git

En lugar de mantener los contratos manualmente, puedes sincronizarlos desde un repositorio git:

  1. Haz clic en Nuevo Contrato y selecciona Git como tipo de fuente
  2. Elige un repositorio conectado
  3. Especifica la ruta al archivo de spec (ej. api/openapi.yaml)
  4. Define la rama a seguir (por defecto, la rama principal del repositorio)
  5. Archyl obtiene el contenido de la spec y lo mantiene sincronizado

También puedes usar patrones glob para coincidir con múltiples archivos. Por ejemplo, api/**/*.yaml coincidirá con todos los archivos YAML bajo el directorio api/.

Comportamiento de Sincronización

  • Las specs se obtienen del repositorio al crear el contrato
  • Usa el botón Sync para obtener manualmente la última versión
  • La marca de tiempo de la última sincronización se muestra en la tarjeta del contrato

Servidores MCP

Los servidores MCP (Model Context Protocol) exponen tools a los agentes de IA — cada uno con un nombre, una descripción y un JSON Schema para sus entradas. Esa superficie de tools también es un contrato: define lo que un agente tiene permitido hacer. Archyl la documenta como el tipo de contrato MCP.

A diferencia de los otros tipos, los tools de un servidor MCP normalmente no son un archivo en un repo — la lista autoritativa solo existe en tiempo de ejecución, mediante la llamada tools/list. Por eso los contratos MCP admiten dos fuentes.

Pegar la lista de tools

  1. Haz clic en Nuevo Contrato y elige MCP
  2. Mantén la fuente como Manual
  3. Pega el JSON tools/list del servidor — un objeto de la forma { "tools": [ ... ] }
  4. Haz clic en Crear

Archyl valida el documento y renderiza cada tool.

Descubrir desde un endpoint en vivo

Deja que Archyl obtenga los tools directamente desde un servidor en ejecución:

  1. Haz clic en Nuevo Contrato, elige MCP y selecciona Live endpoint como fuente
  2. Introduce la URL del servidor y elige el transporte (HTTP o SSE)
  3. Si el servidor requiere autenticación, elige dónde va el token — una cabecera (ej. X-API-Key) o un parámetro de URL — e introduce el token
  4. Haz clic en Descubrir tools — Archyl se conecta, ejecuta el handshake y lista cada tool y sus parámetros
  5. Revisa los tools descubiertos y luego haz clic en Crear

Para refrescar los tools más tarde, edita el contrato y vuelve a ejecutar Descubrir tools.

El descubrimiento se ejecuta en tu navegador, no en los servidores de Archyl. Tu token nunca sale de tu navegador — Archyl almacena los tools descubiertos y los detalles de conexión (URL, transporte, nombre de la cabecera/parámetro) pero nunca el token en sí. Como la llamada se origina en tu máquina, también puede alcanzar servidores en localhost o en tu red privada.

El único requisito: el servidor MCP debe permitir el origen de este sitio (CORS) para que tu navegador pueda leer la respuesta. Para servidores que controlas es un pequeño cambio de configuración; de lo contrario, usa la opción de pegar de arriba.

El visualizador de tools MCP

Cada tool se muestra con su nombre, descripción y parámetros de entrada (derivados de su JSON Schema), con el schema en bruto disponible por tool. Como los otros tipos de contrato, el visualizador es de solo lectura y refleja la lista de tools almacenada.

Vincular Contratos a la Arquitectura

Los contratos de API cobran significado cuando se vinculan a los elementos C4 que describen. Un contrato puede vincularse a sistemas, contenedores, componentes o elementos de código.

Agregar Vínculos

  1. Abre la página de detalle de un contrato
  2. Haz clic en Vincular a Elemento
  3. Selecciona el nivel C4 (Sistema, Contenedor, Componente o Código)
  4. Elige el elemento destino
  5. El vínculo aparece tanto en el contrato como en el panel de detalle del elemento

Ver Contratos Vinculados

En el diagrama, haz clic derecho en cualquier elemento para abrir su panel de detalle. Los contratos de API vinculados aparecen en la sección Contratos con:

  • Nombre y versión del contrato
  • Badge del tipo de protocolo (HTTP, gRPC, GraphQL, Async, MCP)
  • Enlace a la especificación completa

Entradas de Servidor

Cada contrato puede definir múltiples entradas de servidor — útil para documentar diferentes entornos o regiones.

Campo Descripción
URL La URL base del servidor (ej. https://api.example.com/v1)
Descripción Entorno o propósito (ej. "Producción", "Staging")

El Visualizador de Especificaciones

Archyl renderiza tus especificaciones de API con un visualizador interactivo:

  • OpenAPI — Endpoints agrupados por tag, con esquemas de request/response, parámetros y ejemplos
  • gRPC — Definiciones de servicios, métodos RPC y tipos de mensajes
  • GraphQL — Tipos, queries, mutations y subscriptions
  • AsyncAPI — Canales, mensajes y esquemas
  • MCP — Tools, cada uno con su descripción y parámetros de entrada (desde su JSON Schema)

El visualizador es de solo lectura y siempre refleja el contenido actual del contrato.

Canales de Eventos

Los canales de eventos documentan el lado de mensajería asíncrona de tu arquitectura — topics de Kafka, colas SQS, exchanges de RabbitMQ, y similares.

Crear un Canal de Eventos

  1. Navega a tu proyecto
  2. Abre la pestaña Canales de Eventos
  3. Haz clic en Nuevo Canal
  4. Configura el canal:
Campo Descripción
Nombre Nombre del canal (ej. "Eventos de Orden Creada")
Dirección produce o consume
Tipo de Broker Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar o Custom
Nombre del Topic El nombre real del topic o cola
Formato de Schema JSON Schema, Avro, Protobuf o Text
Schema de Valor La definición del schema del payload del evento

Vinculación a la Arquitectura

Los canales de eventos siguen el mismo modelo de vinculación que los contratos de API. Vincula un canal a los sistemas, contenedores o componentes que producen o consumen sus eventos. Esto hace que los flujos de mensajes sean visibles directamente en el diagrama de arquitectura.

Buenas Prácticas

Mantén las Specs Actualizadas

  • Usa la sincronización git para specs que viven en tu codebase
  • Versiona tus contratos siguiendo el versionado semántico
  • Actualiza el contrato cuando la API cambie

Vincula Todo

  • Cada contenedor que sirve una API debería tener al menos un contrato vinculado
  • Vincula los canales de eventos tanto a productores como a consumidores
  • Usa los vínculos para hacer que el diagrama se auto-documente

Organiza por Servicio

  • Un contrato por servicio o contexto delimitado
  • Usa nombres descriptivos coherentes con el nombrado de tu arquitectura
  • Incluye la versión de la API en el campo de versión del contrato

Documenta los Servidores

  • Agrega entradas de servidor para cada entorno
  • Incluye endpoints internos y externos
  • Mantén las URLs actualizadas cuando la infraestructura cambie

Próximos Pasos