API Contracts: Tus especificaciones de API, vinculadas a tu arquitectura
Hace unas semanas, estaba revisando la arquitectura de un sistema con un equipo que tenía un diagrama C4 precioso. Los containers estaban bien definidos. Las relaciones tenían etiquetas claras. Todo se veía genial — hasta que alguien preguntó "¿cómo es realmente la API entre el Order Service y el Payment Gateway?"
Silencio. El diagrama decía "REST/JSON." La especificación OpenAPI vivía en un repositorio diferente. La lista real de endpoints estaba en una página de Notion que no se había actualizado desde que el último becario se fue. Tres fuentes de verdad para una sola superficie de API, y ninguna coincidía.
Esto es absurdamente común. Las especificaciones de API son algunos de los artefactos más precisos y legibles por máquinas en un código fuente. Sin embargo, en la documentación de arquitectura, son invisibles. Tienes una caja, una flecha y una etiqueta de protocolo. El contrato real — los endpoints, los esquemas, los campos — vive en otro lugar completamente diferente.
Construimos API Contracts para solucionar esto. Tus especificaciones de API ahora viven dentro de tu arquitectura, vinculadas a los elementos que las implementan y consumen.
Cuatro protocolos, un solo hogar
Los sistemas modernos rara vez hablan un solo protocolo. Tu API pública es REST, tus servicios internos se comunican por gRPC, y tu frontend obtiene datos a través de GraphQL. Cada uno tiene su propio formato de especificación, sus propias herramientas, su propio ecosistema de documentación.
Los API Contracts de Archyl soportan los cuatro:
OpenAPI / Swagger — Importa tus especificaciones OpenAPI 3.x o Swagger 2.0 y obtén un visor de referencia interactivo impulsado por Scalar. Los endpoints se agrupan, los parámetros se documentan, los esquemas son expandibles. Es la misma experiencia que obtendrías con una herramienta dedicada de documentación de API, integrada directamente en tu espacio de trabajo de arquitectura.
gRPC / Protocol Buffers — Pega o sincroniza tus definiciones .proto. El visor renderiza servicios, métodos, tipos de mensajes y enums con resaltado de sintaxis e indentación adecuada. No más búsquedas entre archivos proto para entender qué expone un servicio.
GraphQL — Importa tu esquema y explora tipos, queries, mutations y subscriptions. Y si has configurado endpoints de servidor, obtienes un playground GraphiQL completo — escribe queries, ejecútalas contra tu API real y explora el esquema interactivamente, todo sin salir de Archyl.
AsyncAPI — Define tus APIs basadas en eventos con especificaciones AsyncAPI. El visor renderiza canales, operaciones, esquemas de mensajes y bindings de servidor con resaltado de sintaxis completo. Ya sea que uses Kafka, RabbitMQ, NATS o WebSockets, los contratos AsyncAPI documentan qué eventos producen y consumen tus servicios.
Importa desde Git o pega directamente
Las especificaciones de API cambian. Se añade un endpoint, se depreca un campo, se lanza una nueva versión. Si tu documentación requiere copiar y pegar manualmente para mantenerse actualizada, no se va a mantener actualizada.
Por eso los API Contracts soportan dos modos de origen:
Git Sync conecta tu contrato a un archivo de especificación en un repositorio. Apúntalo a tu openapi.yaml, tu service.proto, tu schema.graphql o tu asyncapi.yaml, y Archyl obtiene el contenido directamente. Cuando la especificación cambia en el origen, presiona sincronizar y el contrato se actualiza. Esto funciona con todos los proveedores de git que Archyl soporta — GitHub, GitLab, Bitbucket, Azure DevOps e instancias auto-alojadas.
Manual es para equipos que no guardan especificaciones en git, o para prototipado rápido. Pega el contenido de tu especificación directamente y edítalo en el momento. Útil para redactar un contrato antes de que el servicio exista, o para importar una especificación de una API de terceros que no controlas.
Ambos modos soportan versionado, para que puedas rastrear qué versión del contrato estás documentando.
Vinculado a tu arquitectura
Aquí es donde los API Contracts se convierten en más que un visor de especificaciones.
Cada contrato puede vincularse a uno o más elementos C4 — sistemas, containers, componentes o elementos de código. Una especificación OpenAPI puede vincularse al container del API Gateway que la sirve. Un proto gRPC puede vincularse al componente del microservicio que lo implementa. Un esquema GraphQL puede vincularse al BFF (Backend for Frontend) que lo expone.
Estos vínculos son bidireccionales. Desde el contrato, ves qué elementos de arquitectura se relacionan con él. Desde el panel de detalle del elemento en el diagrama, ves qué contratos describen su superficie de API. Cuando haces clic derecho en un container en el canvas, puedes vincular y desvincular contratos directamente desde el menú contextual.
Esto cierra la brecha que describí al principio. Cuando alguien pregunta "¿cómo es la API entre estos dos servicios?", la respuesta está a un solo clic. No en una herramienta diferente, no en un repo diferente — justo ahí en el diagrama.
Canales de Eventos
Las arquitecturas basadas en eventos son notoriamente difíciles de documentar. ¿Qué servicio publica en qué topic? ¿Cuál es el esquema del mensaje? ¿Quién lo consume?
Los Canales de Eventos de Archyl aportan visibilidad a tu comunicación asíncrona. Cada contrato AsyncAPI hace aflorar automáticamente los canales que define — topics, colas, streams — y los mapea a los elementos C4 que producen y consumen eventos.
En el diagrama, los canales de eventos aparecen como tipos de conexión distintos, dejando inmediatamente claro qué relaciones son llamadas API síncronas y cuáles son flujos de eventos asíncronos. Esto es crítico para entender el comportamiento del sistema: una llamada REST entre dos servicios tiene características de fiabilidad y acoplamiento muy diferentes a un evento publicado en un message broker.
También puedes crear canales de eventos independientemente de los contratos AsyncAPI, útil para documentar sistemas de mensajería legacy o protocolos propietarios que no tienen una especificación formal.
Visores interactivos
No queríamos que los contratos fueran bloques de texto crudo. Cada protocolo tiene un visor construido a medida:
El visor de OpenAPI renderiza una referencia de API completamente interactiva. Los endpoints se organizan por tag, con esquemas de request/response expandibles, documentación de parámetros y detalles de autenticación. Si has definido URLs de servidor, el visor las muestra para que los desarrolladores sepan a dónde enviar las peticiones. Es una experiencia real de documentación de API, no un volcado de YAML con resaltado de sintaxis.
El visor de Protocol Buffer renderiza definiciones proto con coloreo de sintaxis adecuado, haciendo que servicios, RPCs y estructuras de mensajes sean fáciles de escanear.
El visor de GraphQL resalta tipos, campos y directivas. Y cuando has configurado un endpoint de servidor, una segunda pestaña abre un playground GraphiQL completo. Puedes escribir y ejecutar queries contra tu API en vivo, explorar el esquema a través de introspección y probar mutations — todo integrado en Archyl. Si tu API GraphQL tiene múltiples entornos (staging, producción), puedes definir múltiples entradas de servidor y alternar entre ellas.
El visor de AsyncAPI renderiza tus definiciones de API basadas en eventos con listados de canales, esquemas de mensajes y configuraciones de servidor/broker. Cada canal muestra sus operaciones (publish/subscribe), esquemas de payload y bindings — dando a los desarrolladores una imagen clara de tu superficie de comunicación basada en eventos.
Cómo empezar
Navega a cualquier proyecto y abre la sección de API Contracts desde la barra lateral. Haz clic en "Add Contract" y elige tu tipo de protocolo y modo de origen.
Para contratos con origen en git, conecta un repositorio (o reutiliza uno ya conectado a tu proyecto), especifica la ruta del archivo y la rama, y Archyl obtiene la especificación. Para contratos manuales, pega el contenido directamente.
Una vez creado, ve al diagrama y vincula el contrato a los elementos C4 relevantes. A partir de ese momento, cualquiera que explore la arquitectura puede profundizar en la superficie real de la API desde el propio diagrama.
Por qué esto importa
Los diagramas de arquitectura son poderosos para mostrar estructura — qué existe y cómo se conectan las cosas. Pero siempre han sido débiles en interfaces. Una flecha de relación etiquetada como "REST/HTTPS" no te dice casi nada sobre lo que realmente fluye entre dos servicios. Un evento publicado en un topic de Kafka es aún más opaco — a menos que tengas la especificación AsyncAPI y el mapeo de canales justo ahí.
Los API contracts llenan esa brecha. Añaden precisión a las flechas. Cuando un nuevo miembro del equipo mira tu arquitectura y ve una conexión entre la Mobile App y el API Gateway, puede abrir inmediatamente la especificación OpenAPI y entender exactamente qué endpoints están disponibles, qué estructuras de datos se intercambian y qué autenticación se requiere.
Esto es documentación de arquitectura que se gana su lugar. No porque alguien la impuso, sino porque responde preguntas reales que surgen todos los días.
¿Ya usas Archyl para tu arquitectura? Explora la funcionalidad de API Contracts en tu proyecto. ¿Eres nuevo en la plataforma? Aprende sobre el modelo C4 y cómo el descubrimiento impulsado por IA puede generar tu diagrama de arquitectura automáticamente.