¿Cómo admite OpenAPI las API asíncronas?

¿Cómo admite OpenAPI las API asíncronas? #

El auge de la comunicación asíncrona se ha convertido en una de las tendencias clave de la ingeniería de software moderna. A diferencia de la comunicación síncrona, en la que la solicitud y la respuesta se producen de forma secuencial, las API asíncronas permiten patrones de comunicación más flexibles y resilientes. La especificación OpenAPI (OAS) es el marco de referencia para definir API REST síncronas, pero a medida que crece la necesidad de API asíncronas, los desarrolladores e ingenieros pueden preguntarse cómo admite OpenAPI este nuevo paradigma.

Este artículo explora cómo admite OpenAPI las API asíncronas, cómo definir endpoints asíncronos y presenta tecnologías relacionadas como AsyncAPI, diseñada específicamente para las API asíncronas.

Comprender las API asíncronas #

Antes de entrar en los detalles de OpenAPI, es fundamental tener claro qué son las API asíncronas. A diferencia de las API síncronas, en las que el cliente envía una solicitud y espera una respuesta inmediata del servidor, las API asíncronas funcionan según el principio de la comunicación no bloqueante:

  • Basadas en eventos: las API asíncronas suelen estar basadas en eventos. Un evento desencadena un mensaje que se envía a un intermediario de mensajes (message broker) o a un servicio, que puede procesarlo a su propio ritmo.
  • No bloqueantes: quien realiza la llamada no espera a que se complete la tarea, lo que permite realizar otras tareas mientras tanto.
  • Adecuadas para la comunicación en tiempo real: se utilizan ampliamente en web sockets, IoT y arquitecturas de microservicios, donde es fundamental el procesamiento en tiempo real o casi real.

Definir API asíncronas con OpenAPI #

La especificación OpenAPI (OAS) está orientada principalmente a las API REST, que son fundamentalmente síncronas. Sin embargo, incluye disposiciones para dar cabida a operaciones asíncronas:

Callbacks #

Los callbacks son una de las funciones de OpenAPI 3.0 que permiten definir interacciones asíncronas. Un callback es, en esencia, una forma de definir una operación de posprocesamiento a la que el servidor volverá a llamar una vez que haya terminado de procesar la solicitud.

Este es un ejemplo de definición OpenAPI para un callback:

paths:
  /createResource:
    post:
      summary: "Create a resource"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Resource"
      responses:
        '201':
          description: "Resource created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
      callbacks:
        onSuccess:
          "{$request.body#/callbackUrl}":
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/OperationStatus"
              responses:
                '200':
                  description: "Callback received"

En este ejemplo, el servidor se comunicará de vuelta con la URL especificada en callbackUrl, e invocará el endpoint de callback definido una vez que haya terminado de procesar la creación del recurso.

Webhooks #

Aunque no forman parte explícita de OpenAPI, los webhooks permiten lograr un procesamiento asíncrono. El soporte para describir webhooks se ajusta estrechamente a este patrón; se introdujo en OpenAPI 3.1 y se mantiene en OpenAPI 3.2, la versión actual de la OAS. En términos sencillos, los webhooks son callbacks HTTP que se producen cuando ocurre un evento.

Este es un ejemplo para describir una API que admite webhooks:

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        item:
          type: string
        status:
          type: string
  
paths:
  /orders:
    post:
      summary: "Create a new order"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        '202':
          description: "Order accepted"

webhooks:
  orderStatus:
    summary: "Status of an order"
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        '200':
          description: "Webhook received successfully"

En este ejemplo, el endpoint /orders puede notificar a un webhook orderStatus, lo que ofrece un mecanismo claro para difundir actualizaciones asíncronas a las partes interesadas.

AsyncAPI: una especificación complementaria #

Aunque OpenAPI ofrece algunos mecanismos para las API asíncronas, su diseño se centra principalmente en las interacciones REST síncronas. Aquí es donde entra en juego AsyncAPI. AsyncAPI es una especificación para definir API asíncronas, con un enfoque similar al de OpenAPI pero especializada en arquitecturas no bloqueantes y basadas en eventos.

Características principales de AsyncAPI #

  1. Arquitectura basada en eventos: admite de forma nativa los sistemas basados en eventos y recoge los requisitos y matices específicos de la comunicación asíncrona.
  2. Productores y consumidores: define con claridad tanto los productores (servicios que generan eventos) como los consumidores (servicios que reaccionan a los eventos).
  3. Soporte para varios protocolos: puede funcionar con diversos protocolos como MQTT, AMQP, WebSockets, Kafka y más.

Ejemplo de definición AsyncAPI #

Para resaltar el contraste, este es un ejemplo de definición AsyncAPI para una aplicación de chat en tiempo real:

asyncapi: 2.0.0
info:
  title: Chat API
  version: '1.0.0'
servers:
  production:
    url: 'chat.example.com:443'
    protocol: wss
channels:
  user/signedup:
    description: Channel for new user signups
    publish:
      summary: "New user has signed up"
      message:
        contentType: application/json
        payload:
          type: object
          properties:
            userId:
              type: string
              description: "ID of the new user"
  message/sent:
    description: Channel for sent messages
    subscribe:
      summary: "Subscribe to sent messages"
      message:
        contentType: application/json
        payload:
          type: object
          properties:
            messageId:
              type: string
            sender:
              type: string
            content:
              type: string

En esta especificación:

  • Los channels equivalen a lo que son los paths en OpenAPI.
  • Cada canal representa un tema o un flujo de eventos.
  • Las operaciones publish y subscribe reflejan la naturaleza de la comunicación asíncrona.

Integrar OpenAPI y AsyncAPI #

Muchas arquitecturas modernas no son exclusivamente síncronas ni asíncronas, sino que combinan ambos enfoques. Es posible, y con frecuencia necesario, integrar las especificaciones OpenAPI y AsyncAPI para describir de forma completa las distintas partes de tu API.

Ejemplo de uso combinado #

Consideremos una plataforma de comercio electrónico que utiliza una combinación de comunicación síncrona para la realización de pedidos y asíncrona para las notificaciones de pedidos.

Parte OpenAPI: #

paths:
  /order:
    post:
      summary: "Place a new order"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Order"
      responses:
        '201':
          description: "Order placed successfully"
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        item:
          type: string
        quantity:
          type: integer
          format: int32
          description: "Number of items ordered"
        price:
          type: number
          format: float
          description: "Price of the order"

Parte AsyncAPI: #

asyncapi: 2.0.0
info:
  title: Order Notification API
  version: '1.0.0'
servers:
  production:
    url: 'orders.example.com:443'
    protocol: wss
channels:
  order/created:
    description: Channel for order creation notifications
    publish:
      summary: "Notify when an order is created"
      message:
        contentType: application/json
        payload:
          type: object
          properties:
            orderId:
              type: string
            status:
              type: string
              enum: [created, confirmed, shipped]

En este escenario:

  • OpenAPI define la parte síncrona (el endpoint /order), donde los clientes realizan pedidos.
  • AsyncAPI define la parte asíncrona (el canal order/created), donde los clientes pueden recibir notificaciones en tiempo real.

Conclusión #

OpenAPI admite las API asíncronas hasta cierto punto, en concreto mediante funciones como los callbacks y los webhooks. Sin embargo, para obtener especificaciones completas, sólidas y detalladas dedicadas a la comunicación asíncrona, AsyncAPI es una herramienta especializada y complementaria. Al integrar OpenAPI y AsyncAPI, los desarrolladores pueden aprovechar lo mejor de ambos mundos y asegurarse de que sus aplicaciones estén bien preparadas para gestionar una combinación de comunicación síncrona y asíncrona.

Para obtener más información, puedes visitar OpenAPI y AsyncAPI. Ambos frameworks evolucionan continuamente y reflejan las necesidades y prácticas del diseño de API moderno. Adoptar OpenAPI y AsyncAPI como parte de tu estrategia de API no solo mejorará la flexibilidad de tu sistema, sino que también preparará tu arquitectura para el futuro ante la evolución de las tendencias tecnológicas.

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

Este sitio web no está afiliado a la OpenAPI Initiative.