¿Qué es AsyncAPI y en qué se diferencia de OpenAPI? #

A medida que las arquitecturas basadas en eventos, las colas de mensajes y los patrones de comunicación en tiempo real se han vuelto habituales en los sistemas de software modernos, ha crecido la necesidad de contar con una forma estándar de describir las API asíncronas. AsyncAPI es la respuesta: una especificación abierta para API basadas en eventos que hace por ellas lo que OpenAPI hace por las API REST. Comprender la relación entre ambos estándares, con sus similitudes, sus diferencias y los escenarios en los que conviene cada uno, es esencial para cualquier equipo que cree o consuma API modernas.

¿Qué es AsyncAPI? #

AsyncAPI es una especificación abierta mantenida por la AsyncAPI Initiative, un proyecto de la Linux Foundation. Al igual que OpenAPI, utiliza YAML o JSON para describir las interfaces de las API en un formato legible por máquinas. Pero mientras que OpenAPI describe interacciones HTTP síncronas de solicitud y respuesta, AsyncAPI describe interacciones asíncronas basadas en mensajes: los eventos, los mensajes y los canales a través de los cuales se comunican los sistemas mediante protocolos como:

• Apache Kafka
• RabbitMQ (AMQP)
• MQTT (mensajería para IoT)
• WebSockets
• Eventos enviados por el servidor (SSE)
• Google Cloud Pub/Sub
• AWS SNS/SQS
• NATS
• Solace

AsyncAPI 2.x introdujo el concepto de canales (temas, colas, asuntos) y de operaciones (publicar o suscribirse) como los principales conceptos organizativos, en sustitución del modelo de ruta y método de OpenAPI.

AsyncAPI 3.0, publicada en 2024, perfeccionó aún más el modelo: separó con mayor claridad la estructura de los canales de las operaciones de la aplicación y mejoró el soporte multiprotocolo. La versión actual, 3.1.0, se apoya en ese modelo con aclaraciones y pequeñas incorporaciones en lugar de cambios estructurales.

La diferencia fundamental: síncrono frente a asíncrono #

La distinción fundamental entre OpenAPI y AsyncAPI es el modelo de comunicación que describen:

En OpenAPI, un cliente envía una solicitud y espera la respuesta del servidor. En AsyncAPI, un productor envía un mensaje a un canal y uno o varios consumidores lo reciben, posiblemente mucho después, de forma independiente y sin una conexión directa con el productor.

Estructura de un documento AsyncAPI #

Un documento de AsyncAPI 3.0 comparte similitudes estructurales con OpenAPI, pero utiliza campos de nivel superior diferentes:

asyncapi: 3.0.0
info:
  title: Order Events API
  version: 1.0.0
  description: Events emitted when order status changes

servers:
  production:
    host: kafka.example.com:9092
    protocol: kafka

channels:
  orderPlaced:
    address: orders.placed
    messages:
      orderPlacedMessage:
        $ref: '#/components/messages/OrderPlaced'

  orderShipped:
    address: orders.shipped
    messages:
      orderShippedMessage:
        $ref: '#/components/messages/OrderShipped'

operations:
  receiveOrderPlaced:
    action: receive
    channel:
      $ref: '#/channels/orderPlaced'

  sendOrderShipped:
    action: send
    channel:
      $ref: '#/channels/orderShipped'

components:
  messages:
    OrderPlaced:
      payload:
        type: object
        required: [orderId, customerId, timestamp]
        properties:
          orderId:
            type: string
            format: uuid
          customerId:
            type: string
          timestamp:
            type: string
            format: date-time

Elementos estructurales clave:

• channels: los canales de comunicación (temas de Kafka, colas de AMQP, flujos de WebSocket).
• operations: lo que hace la aplicación en esos canales: send (producir) o receive (consumir).
• servers: los datos de conexión del intermediario de mensajes (message broker) o del servidor, incluido el protocolo.
• components/messages: definiciones de mensajes reutilizables, incluidos los esquemas de las cargas útiles.

Conceptos compartidos: JSON Schema y seguridad #

Tanto AsyncAPI como OpenAPI utilizan JSON Schema para definir los esquemas de las cargas útiles. Esto significa que los equipos con experiencia en OpenAPI pueden aplicar de inmediato sus conocimientos sobre esquemas a los documentos de AsyncAPI. AsyncAPI 3.x se alinea con JSON Schema Draft 2020-12, igual que el vocabulario de esquemas de OpenAPI 3.1.

Ambas especificaciones también admiten definiciones de esquemas de seguridad, aunque los mecanismos de autenticación relevantes para los intermediarios de mensajes (SASL, mTLS, claves de API) difieren de los que se usan habitualmente en las API HTTP.

Ecosistema de herramientas #

AsyncAPI cuenta con un ecosistema de herramientas en crecimiento:

• AsyncAPI Studio: un editor web para documentos de AsyncAPI, similar a Swagger Editor para OpenAPI.
• AsyncAPI Generator: genera documentación, código de servidor y código de cliente a partir de documentos de AsyncAPI. Admite plantillas para Node.js, Python, Java y más.
• Microcks: simulación (mocking) y pruebas de contrato para OpenAPI y AsyncAPI en una sola plataforma.
• Spectral: compatibilidad con linter para documentos de AsyncAPI junto con OpenAPI.
• AsyncAPI Diff: detecta cambios incompatibles entre versiones de documentos de AsyncAPI.

El catálogo de herramientas de AsyncAPI enumera el ecosistema completo.

Cuándo usar OpenAPI y cuándo AsyncAPI #

La elección entre OpenAPI y AsyncAPI viene determinada por el patrón de comunicación que se quiere describir, no por una preferencia:

Usa OpenAPI cuando:

• Describas API REST con semántica HTTP de solicitud y respuesta.
• Crees API CRUD, API de consulta o patrones de RPC sobre HTTP.
• Generes SDK de cliente HTTP o esqueletos de servidor.
• Documentes webhooks (compatibles de forma nativa en OpenAPI 3.1).

Usa AsyncAPI cuando:

• Describas temas de Kafka, colas de RabbitMQ o temas de MQTT.
• Documentes flujos de WebSocket o canales de eventos enviados por el servidor.
• Crees microservicios basados en eventos que se comuniquen a través de un intermediario de mensajes.
• Describas la interfaz de publicación/suscripción de un servicio en una arquitectura basada en eventos.

Muchos sistemas reales usan ambas: una API REST descrita con OpenAPI para las interacciones síncronas y flujos de eventos descritos con AsyncAPI para las notificaciones asíncronas. Microcks y plataformas como Apicurio admiten ambas especificaciones en el mismo flujo de gobernanza y pruebas.

La colaboración entre AsyncAPI y OpenAPI #

Las iniciativas AsyncAPI y OpenAPI colaboran activamente. Ambas son proyectos de la Linux Foundation, comparten JSON Schema como vocabulario de esquemas común y se alinean en prácticas de gobernanza y de herramientas. La especificación CloudEvents, un proyecto de la CNCF para estandarizar los formatos de envoltorio de eventos, complementa a ambas especificaciones y se documenta cada vez más con AsyncAPI.

Conclusión #

AsyncAPI es el equivalente de OpenAPI para la comunidad de las API basadas en eventos: una especificación legible por máquinas, basada en JSON Schema, para describir los canales, los mensajes y las operaciones de los sistemas asíncronos. Mientras que OpenAPI destaca al documentar las API REST, AsyncAPI es la herramienta adecuada para las interfaces de Kafka, AMQP, MQTT, WebSocket y otros protocolos de mensajería. Juntas, las dos especificaciones ofrecen una capa de descripción integral para toda la gama de patrones de comunicación de las API modernas: síncronos y asíncronos, HTTP y mensajería.

Última actualización: 12 de agosto de 2026.