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 y AsyncAPI, con sincronización git opcional.

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

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 o Async
    • 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

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)
  • 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

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