¿Qué son las expresiones en tiempo de ejecución de OpenAPI y cómo se utilizan?

¿Qué son las expresiones en tiempo de ejecución de OpenAPI y cómo se utilizan? #

Las expresiones en tiempo de ejecución (runtime expressions) son una característica especializada de la especificación OpenAPI que permite que ciertos campos hagan referencia a valores de la solicitud o la respuesta HTTP en el momento en que se realiza la llamada a la API. A diferencia de los valores estáticos de un documento OpenAPI, que se conocen en tiempo de diseño, las expresiones en tiempo de ejecución se evalúan de forma dinámica sobre el mensaje HTTP real. Aparecen en dos contextos específicos: los links (que definen relaciones entre operaciones) y los callbacks (que definen URL de webhook derivadas de los datos de la solicitud).

¿Qué problema resuelven las expresiones en tiempo de ejecución? #

Los documentos OpenAPI describen contratos estáticos: la forma de las solicitudes y las respuestas se define una sola vez y se aplica a todas las llamadas. Sin embargo, algunos comportamientos de las API son inherentemente dinámicos: la URL de una solicitud posterior depende del ID devuelto en la primera respuesta; la URL de un callback de webhook la proporciona el cliente en la solicitud original.

Las expresiones en tiempo de ejecución ofrecen una forma estandarizada de expresar estas referencias dinámicas sin recurrir a descripciones en texto libre. Una expresión como $response.body#/id significa sin ambigüedad “el valor del campo id en el cuerpo de la respuesta”: una referencia legible por máquinas que las herramientas pueden entender y utilizar.

Sintaxis de las expresiones en tiempo de ejecución #

La sintaxis sigue este patrón:

expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
source = ( header-reference | query-reference | path-reference | body-reference )
header-reference = "header." token
query-reference = "query." name
path-reference = "path." name
body-reference = "body" ["#" json-pointer]

Referencias de origen #

Expresión	Descripción
`$url`	La URL completa de la solicitud
`$method`	El método HTTP de la solicitud (`GET`, `POST`, etc.)
`$statusCode`	El código de estado HTTP de la respuesta
`$request.header.{name}`	El valor de un encabezado concreto de la solicitud
`$request.query.{name}`	El valor de un parámetro de consulta concreto
`$request.path.{name}`	El valor de un parámetro de ruta concreto
`$request.body`	El cuerpo completo de la solicitud
`$request.body#/pointer`	Un campo del cuerpo de la solicitud mediante un JSON Pointer
`$response.header.{name}`	El valor de un encabezado concreto de la respuesta
`$response.body`	El cuerpo completo de la respuesta
`$response.body#/pointer`	Un campo del cuerpo de la respuesta mediante un JSON Pointer

La sintaxis de JSON Pointer (RFC 6901) se utiliza para navegar por objetos anidados. Un puntero como #/data/user/id navega hasta body.data.user.id en el cuerpo de la respuesta.

Uso en links #

Los links son el principal caso de uso de las expresiones en tiempo de ejecución. Un link describe cómo el resultado de una operación puede utilizarse como entrada de otra, modelando las relaciones de tipo hypermedia entre las operaciones de la API.

Los links se definen en components/links y se referencian desde los objetos de respuesta:

paths:
  /users:
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          links:
            GetUserById:
              operationId: getUser
              parameters:
                userId: '$response.body#/id'
              description: >
                The `id` value returned in the response can be used as
                the `userId` parameter in `GET /users/{userId}`
            ListUserOrders:
              operationId: listUserOrders
              parameters:
                userId: '$response.body#/id'
              description: >
                The `id` value can be used as `userId` in
                `GET /users/{userId}/orders`

  /users/{userId}:
    get:
      summary: Get a user
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string

En este ejemplo:

La operación createUser devuelve un objeto User con un campo id
El link GetUserById dice: “usa $response.body#/id (el id de la respuesta de creación) como parámetro userId de la operación getUser”
Las herramientas de documentación pueden mostrarlo como un enlace clicable entre operaciones; los clientes de la API pueden usarlo para encadenar operaciones automáticamente

Parámetros del link frente a requestBody #

Los links pueden hacer referencia a parámetros (de ruta, de consulta, de encabezado o de cookie) o a un requestBody. El objeto parameters asigna los nombres de los parámetros a expresiones en tiempo de ejecución:

links:
  CreateOrderForUser:
    operationId: createOrder
    parameters:
      userId: '$response.body#/id'
    requestBody:
      description: Use the user ID from the create response
      $ref: '#/components/requestBodies/CreateOrderRequest'

Uso en callbacks #

Los callbacks describen notificaciones al estilo de los webhooks que el servidor enviará al cliente. A menudo, la URL del callback la proporciona el cliente en el cuerpo de la solicitud original. Las expresiones en tiempo de ejecución permiten derivar la URL del callback a partir de los campos de la solicitud:

paths:
  /subscriptions:
    post:
      summary: Subscribe to order status updates
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [callbackUrl]
              properties:
                callbackUrl:
                  type: string
                  format: uri
                  description: URL to receive order status updates
                  example: https://myapp.example.com/webhooks/orders
                eventTypes:
                  type: array
                  items:
                    type: string
      callbacks:
        onOrderStatusUpdate:
          '{$request.body#/callbackUrl}':
            post:
              summary: Order status update notification
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/OrderStatusEvent'
              responses:
                "200":
                  description: Callback received successfully

La clave de ruta del callback '{$request.body#/callbackUrl}' es la expresión en tiempo de ejecución entre llaves. Significa: “al enviar el webhook, usa como URL el valor de callbackUrl del cuerpo de la solicitud de suscripción”.

Esto hace que la URL de destino del callback sea dinámica y se derive de la llamada real a la API, que es el modelo correcto para las API de registro de webhooks.

Expresiones en tiempo de ejecución frente a expresiones de plantilla #

Conviene distinguir las expresiones en tiempo de ejecución de la sintaxis de plantilla de las variables de servidor de OpenAPI ({variable}). Las plantillas de variables de servidor usan {name} sin el signo de dólar y se sustituyen en el momento de la configuración (antes de cualquier llamada a la API), mientras que las expresiones en tiempo de ejecución usan la sintaxis $source.path y se evalúan sobre mensajes HTTP reales durante la ejecución.

Compatibilidad de las herramientas #

La compatibilidad con las expresiones en tiempo de ejecución varía según la herramienta:

Renderizadores de documentación (Swagger UI, Redoc, Scalar): muestran los links como relaciones navegables entre operaciones, indicando qué operaciones pueden seguir a una respuesta determinada
Generadores de SDK: pueden usar los links para generar métodos auxiliares del lado del cliente que encadenan operaciones automáticamente (por ejemplo, createUser().then(user => getUser(user.id)))
Servidores simulados (mock) como Prism: muestran la información de los links en las respuestas, pero por lo general no ejecutan automáticamente las operaciones enlazadas
Exploradores de API: pueden usar los links para rellenar previamente las entradas de una operación con valores de las salidas de respuestas anteriores

Limitaciones #

Las expresiones en tiempo de ejecución de OpenAPI son descriptivas, no ejecutables:

No indican al servidor que realice ninguna acción
No pueden expresar transformaciones complejas (solo referencias simples a campos)
No tienen lógica condicional
Las herramientas no están obligadas a actuar en consecuencia; su presencia en el documento no garantiza ningún comportamiento

Para definir flujos de trabajo de API más complejos, con secuencias, condiciones y transformaciones entre varias operaciones, la especificación Arazzo (una especificación de la OpenAPI Initiative) ofrece un lenguaje de descripción de flujos de trabajo específico construido sobre OpenAPI.

Conclusión #

Las expresiones en tiempo de ejecución de OpenAPI son un mecanismo específico para hacer referencia a valores de la solicitud y la respuesta HTTP en links y callbacks. En los links, expresan las relaciones entre operaciones (cómo la salida de una operación alimenta la entrada de otra), lo que permite a los renderizadores de documentación y a los generadores de SDK mostrar rutas de navegación por la API. En los callbacks, permiten derivar las URL de webhook a partir de los datos de la solicitud proporcionados por el cliente. Aunque su uso se limita a estos dos contextos y la compatibilidad de las herramientas varía, las expresiones en tiempo de ejecución ofrecen un vocabulario legible por máquinas para describir los flujos de datos dinámicos que existen entre las operaciones de una API.

Última actualización: 30 de abril de 2026.