Barbacane: un gateway para todas tus specs de API
Barbacane es un API gateway que toma múltiples archivos de especificación —OpenAPI 3.x y AsyncAPI 3.0.x— y los compila en un único artefacto de runtime, eliminando la desincronización entre servicios que solo se detectaba en producción. El comando acepta N archivos YAML y devuelve un solo gateway.bca con todas las rutas consolidadas.
En 30 segundos
- Barbacane compila OpenAPI 3.x y AsyncAPI 3.0.x juntos en un solo artefacto (
.bca), con un único comando - Un ejemplo real: 4 specs → 23 rutas → 5 plugins → 1
gateway.bca - Los conflictos entre especificaciones se detectan en compilación, no en producción
- Maneja tanto endpoints REST síncronos como consumidores de eventos asíncronos desde el mismo gateway
- Las políticas de seguridad (JWT, API Keys, OAuth2) se definen en las specs y Barbacane las aplica de forma centralizada
El problema: APIs dispersas y desincronizadas
Ponele que tenés tres microservicios en producción: user-service, order-service e inventory-service. Cada uno tiene su OpenAPI. El de inventario además tiene un AsyncAPI porque también emite eventos. Esos cuatro archivos viven en repos diferentes, los despliegan equipos distintos, y la versión que tiene el gateway puede ser de la semana pasada.
El resultado es predecible: un campo renombrado en el contrato de user-service no llega al gateway hasta que alguien lo actualiza a mano. Y ese alguien se olvida. O lo actualiza mal. O lo actualiza en staging pero no en producción.
Las herramientas de spec única no ven ese problema. Validan un archivo de forma aislada, lo dan por bueno, y el conflicto entre servicios aparece en runtime cuando el tráfico real ya está pasando. El ciclo de feedback es: escribir spec → desplegar → descubrir el conflicto en producción → corregir → redesplegar. Lento y caro.
Qué es Barbacane: el gateway unificador
Barbacane es un API gateway escrito en Rust que toma tus especificaciones existentes como entrada directa, sin requerir una DSL separada ni una capa de configuración adicional. Según el anuncio técnico publicado el 5 de mayo de 2026, el compilador acepta múltiples archivos en una sola invocación y produce un artefacto único que es el runtime del gateway.
El enfoque es distinto al de los gateways tradicionales, que tienen su propia configuración (YAML de Kong, JSON de AWS API Gateway, etc.) y requieren que alguien la mantenga sincronizada con las specs. Barbacane elimina esa capa intermedia: tu spec es la configuración del gateway.
OpenAPI vs AsyncAPI: las dos especificaciones que Barbacane maneja
OpenAPI describe APIs síncronas: HTTP request/response, REST, los endpoints que tu frontend llama y espera respuesta inmediata. AsyncAPI describe el otro mundo: mensajes asíncronos, colas, eventos, los consumidores de Kafka o NATS que reaccionan cuando algo pasa. Más contexto en nuestro artículo sobre cómo configurar correctamente tu infraestructura.
En sistemas modernos coexisten las dos. Un servicio puede exponer un endpoint REST para consultas y al mismo tiempo emitir eventos cuando hay cambios de estado. Hasta ahora, eso significaba dos mundos de configuración separados.
Barbacane los maneja simultáneamente. El compilador parsea tanto OpenAPI 3.x como AsyncAPI 3.0.x y los trata como ciudadanos de primera clase del mismo artefacto.
Cómo funciona la compilación de múltiples especificaciones
El flujo es directo. Pasás los archivos al compilador en una sola invocación:
barbacane compile services/user-service/openapi.yaml services/order-service/openapi.yaml services/inventory-service/openapi.yaml services/inventory-service/asyncapi.yaml
El compilador parsea cada archivo, valida las specs, extrae todas las rutas (tanto HTTP de OpenAPI como canales de AsyncAPI), las consolida y genera un único gateway.bca. La salida te dice exactamente qué obtuviste:
compiled 4 spec(s) to gateway.bca (23 routes, 5 plugin(s) bundled)
Cuatro archivos, veintitrés rutas, cinco plugins, un artefacto. Si hay un conflicto entre specs (dos servicios con el mismo path, tipos incompatibles), la compilación falla ahí. No en producción tres horas después.
Gateway API unificado microservicios: ventajas del enfoque de fuente única
Lo que cambia con este enfoque no es trivial. Si tu spec cambia, el gateway cambia. No hay paso intermedio donde alguien tenga que acordarse de actualizar la configuración del gateway también. Lo explicamos a fondo en nuestro artículo sobre distribuir servicios en múltiples regiones.
- Validación en compilación: los conflictos entre especificaciones se detectan antes de desplegar
- Sin drift de configuración: la spec es el artefacto; no puede haber desincronización
- Visibilidad cross-service: el compilador ve todas las specs juntas y puede detectar inconsistencias que herramientas de spec única no ven
- Auditoría directa: cualquiera puede ver qué rutas tiene el gateway mirando las specs
¿Y qué pasaba antes con los gateways tradicionales? Exacto: tenías la spec del servicio por un lado y la configuración del gateway por otro, y rezabas para que alguien los mantuviera sincronizados.
Orquestación de rutas: REST, eventos y todo junto
El routing en Barbacane unifica las dos naturalezas. Las rutas que vienen de OpenAPI se mapean a endpoints HTTP de los servicios REST. Las que vienen de AsyncAPI se mapean a integraciones de eventos: Kafka, NATS, AWS Lambda.
Centralizar ambos en el mismo gateway tiene una ventaja concreta: las políticas se aplican una sola vez. Rate limiting, autenticación, logging, transformaciones de payload: se definen en el gateway y se aplican a todos los flujos, síncronos y asíncronos, sin duplicar lógica en cada servicio.
Para equipos que corren infraestructura en la nube (o en servidores propios a través de proveedores como donweb.com), esta centralización reduce la superficie de error en producción.
Seguridad centralizada: JWT, API Keys, OAuth2
El problema clásico de seguridad en microservicios es que cada servicio implementa su propia lógica de autenticación. El resultado es que tenés diez implementaciones distintas de validación JWT, algunas bien hechas y otras no tanto (spoiler: siempre hay alguna que no tanto).
Con Barbacane, las políticas de seguridad se definen en las especificaciones OpenAPI usando los security schemes estándar del formato. El compilador las extrae y las aplica de forma centralizada en el gateway. JWT, API Keys, OAuth2: todo configurado una vez, aplicado en todos los endpoints.
Esto no elimina la lógica de negocio de autorización dentro de cada servicio, pero sí elimina la capa de autenticación duplicada. El gateway valida el token; el servicio confía en que el gateway ya hizo esa validación.
Despliegue con hot-reload y sin tiempo de inactividad
Cuando actualizás una spec, recompilás y obtenés un nuevo gateway.bca. Barbacane puede cargar el nuevo artefacto sin reiniciar el proceso del gateway.
Eso significa que el ciclo de actualización es: modificar spec → compilar → recargar. Sin ventana de mantenimiento, sin tráfico rechazado durante el despliegue. Para servicios con SLAs de disponibilidad, la diferencia entre un restart y un hot-reload no es menor.
Tabla comparativa: Barbacane vs enfoque tradicional
| Aspecto | Gateway tradicional | Barbacane |
|---|---|---|
| Fuente de verdad | Configuración del gateway + specs (separadas) | Las specs son el artefacto |
| Detección de conflictos | Runtime (producción) | Compilación (pre-deploy) |
| Soporte AsyncAPI | Varía; generalmente requiere config separada | Nativo, mismo comando |
| Sincronización | Manual o con pipelines adicionales | Automática en compilación |
| Seguridad | Config adicional en el gateway | Extraída de security schemes de OpenAPI |
| Hot-reload | Depende del gateway | Sí, sin downtime |
Errores comunes al unificar especificaciones de API
Asumir que todas las specs tienen el mismo nivel de madurez
Cuando unificás specs de múltiples equipos, la realidad es que algunas están bien mantenidas y otras son el YAML que alguien generó automáticamente en 2023 y nadie tocó más. El compilador de Barbacane va a levantar esos problemas, pero hay que estar preparados para un trabajo de limpieza inicial antes de que todo compile limpio.
Confundir validación de spec con validación de comportamiento
Que la compilación sea exitosa no significa que los servicios se comporten según las specs. Barbacane valida la estructura y detecta conflictos entre especificaciones, pero si un servicio devuelve un campo con el tipo incorrecto en runtime, eso no lo detecta el compilador. Necesitás contract testing complementario.
Versionar el artefacto compilado en vez de las specs
El gateway.bca es un artefacto derivado. Lo que tiene que estar en git son las specs. Si versionás el .bca directamente y alguien lo modifica a mano (cosa que pasa), rompés toda la cadena de trazabilidad. Las specs son la fuente de verdad; el artefacto se genera.
Preguntas Frecuentes
¿Qué es un API gateway que unifica múltiples especificaciones?
Es un gateway que acepta varios archivos de especificación (OpenAPI, AsyncAPI u otros formatos) como entrada y los procesa juntos para generar una configuración de runtime unificada. Barbacane lo hace compilando todas las specs en un único artefacto binario, con validación cruzada entre ellas.
¿Cómo compilar OpenAPI y AsyncAPI juntas?
Con Barbacane, pasás ambos archivos al comando compile en la misma invocación. El compilador los parsea secuencialmente, extrae rutas de ambos formatos y los consolida. No requiere configuración adicional: si el archivo es OpenAPI 3.x o AsyncAPI 3.0.x, Barbacane lo detecta y lo procesa.
¿Puedo usar REST y eventos en el mismo gateway?
Sí, ese es el caso de uso central de Barbacane. Las rutas REST (de OpenAPI) y los canales de eventos (de AsyncAPI) coexisten en el mismo artefacto y comparten las políticas de seguridad, rate limiting y plugins definidos en el gateway.
¿Cómo evitar conflictos entre especificaciones de API?
Barbacane los detecta en tiempo de compilación. Si dos specs definen el mismo path con tipos incompatibles, el compilador falla antes de generar el artefacto. Esto mueve la detección de producción (cuando el tráfico real ya está pasando) a pre-deploy. Complementariamente, el contract testing en CI ayuda a validar el comportamiento real de los servicios.
¿Qué herramientas unifican especificaciones de API?
El campo todavía es emergente. Barbacane es una opción open source disponible en GitHub que compila directamente specs a artefactos de gateway. Otras herramientas como Backstage o plataformas de API management enterprise ofrecen catálogos de specs, pero generalmente no compilan múltiples specs en un artefacto de runtime unificado.
Conclusión
Barbacane ataca un problema real: la brecha entre las especificaciones que los equipos mantienen y la configuración que realmente corre en el gateway. El enfoque de compilar las specs directamente al artefacto de runtime elimina esa brecha por diseño, no por disciplina de proceso.
El soporte simultáneo de OpenAPI y AsyncAPI en un mismo comando es, en mayo de 2026, la parte más diferencial. Si tu arquitectura mezcla REST con eventos (y la mayoría lo hace), tener un gateway unificado que entiende ambos idiomas sin capas de configuración extra vale la pena explorarlo.
Lo que habría que ver en uso real: cómo escala la compilación cuando el número de specs es grande, y cómo maneja versiones concurrentes de la misma spec durante un rollout gradual. El proyecto está activo en GitHub, así que esas respuestas probablemente lleguen pronto.
