¿Qué son los callbacks de OpenAPI?

¿Qué son los callbacks de OpenAPI? #

En el mundo del desarrollo de API, OpenAPI se ha consolidado como un estándar para definir interfaces RESTful. Una característica potente de esta especificación es el concepto de “callbacks”. Aunque en las API RESTful el foco suele estar en el cliente que envía solicitudes al servidor, hay escenarios en los que el servidor necesita enviar información de vuelta al cliente de forma asíncrona. Ahí es donde entran en juego los callbacks de OpenAPI. En este artículo veremos en detalle qué son los callbacks de OpenAPI, por qué podrías necesitarlos y cómo implementarlos.

Comprender los callbacks #

En esencia, un callback en OpenAPI permite que un servidor invoque una URL predefinida en el lado del cliente. Esto resulta útil en flujos de trabajo en los que el servidor necesita notificar al cliente sobre eventos o entregarle los resultados de operaciones de larga duración. En definitiva, los callbacks permiten una comunicación bidireccional entre el cliente y el servidor.

API tradicionales frente a API con callbacks #

En una API RESTful tradicional, la interacción suele ser unidireccional. El cliente envía una solicitud al servidor y este responde. Este patrón síncrono funciona bien en muchas aplicaciones, pero se queda corto en escenarios que requieren comunicación asíncrona. Por ejemplo, piensa en un sistema de procesamiento de pagos en el que el cliente necesita recibir una notificación cuando se completa una transacción.

Client (Payment App) -> Server (Payment Processor)
    "Is the payment complete?"

(Server processes payment...)

Server -> Client
    "Yes, payment complete!"

Enviar solicitudes constantes para comprobar el estado puede ser ineficiente y engorroso. Con los callbacks, el servidor puede notificar directamente al cliente en cuanto se procesa el pago.

Client (Payment App) -> Server (Payment Processor)
    "Process this payment and notify me at http://client.com/callback"

(Server processes payment...)

Server -> Client
    "Payment complete!" (via callback URL)

Implementación en OpenAPI 3.0 #

La especificación OpenAPI 3.0 introduce los callbacks para modelar este comportamiento. A continuación se muestra un esquema de cómo puedes definir callbacks en tu archivo OpenAPI.

Estructura básica #

Una definición OpenAPI que utiliza un objeto de callbacks tendrá este aspecto:

openapi: 3.0.0
info:
  title: Payment API
  version: 1.0.0
paths:
  /processPayment:
    post:
      summary: Initiate a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      callbacks:
        onPaymentComplete:
          '{$request.body.callbackUrl}':
            post:
              summary: Payment complete callback
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/PaymentComplete'
              responses:
                '200':
                  description: Acknowledged
components:
  schemas:
    PaymentRequest:
      type: object
      properties:
        amount:
          type: number
        callbackUrl:
          type: string
    AcceptedResponse:
      type: object
      properties:
        message:
          type: string
    PaymentComplete:
      type: object
      properties:
        status:
          type: string
        transactionId:
          type: string

Explicación #

  1. Objeto de rutas (paths): bajo el endpoint /processPayment se define un método post para iniciar pagos. El cliente incluye en el cuerpo de la solicitud una callbackUrl en la que desea recibir las notificaciones.

  2. Objeto de callbacks (callbacks): el objeto callbacks se define en el método post. La clave onPaymentComplete es un nombre arbitrario para el callback. La clave situada bajo el objeto del callback ('{$request.body.callbackUrl}') es una expresión en tiempo de ejecución que se evalúa como la callbackUrl proporcionada en el cuerpo de la solicitud.

  3. Ruta del callback: bajo la ruta definida por la expresión en tiempo de ejecución se especifica otro método post. Este representa al servidor enviando una solicitud POST a la callbackUrl del cliente una vez completado el pago.

  4. Objeto de componentes (components): la sección components contiene las definiciones de esquemas de PaymentRequest, AcceptedResponse y PaymentComplete, a los que se hace referencia en las rutas.

Casos de uso de los callbacks #

Procesamiento asíncrono #

Si tienes operaciones de larga duración, como el renderizado de vídeo, la carga de archivos o cálculos complejos, los callbacks son ideales para notificar al cliente cuando la tarea ha terminado. Así se evita que el cliente tenga que consultar al servidor de forma incesante.

Sistemas basados en eventos #

En las arquitecturas basadas en eventos, las acciones se desencadenan a partir de eventos. Por ejemplo, la eliminación de un usuario podría provocar una serie de operaciones, y el sistema puede usar callbacks para informar al cliente de que esas operaciones en cascada se han completado o han fallado.

Actualizaciones en tiempo real #

En aplicaciones que requieren actualizaciones en tiempo real, como las aplicaciones de chat o los flujos de datos en vivo, los callbacks ofrecen un mecanismo eficiente para que el servidor envíe actualizaciones en cuanto se producen.

Webhooks #

Los webhooks son una forma especializada de callbacks. Se utilizan principalmente para integrar sistemas distintos. Por ejemplo, una plataforma de comercio electrónico podría usar webhooks para notificar a un sistema de gestión de inventario las ventas y los niveles de existencias.

Buenas prácticas #

  1. Seguridad: asegúrate de validar y autenticar las URL de callback del cliente para evitar usos indebidos. Utiliza HTTPS para proteger los datos transmitidos durante los callbacks.

  2. Reintentos y confirmaciones: implementa un mecanismo de reintentos por si el callback falla. El cliente debe confirmar la recepción del callback para informar al servidor de que el mensaje se recibió correctamente.

  3. Gestión de errores: gestiona adecuadamente los errores en la implementación de tus callbacks. Si se produce un error al enviar un callback, asegúrate de registrarlo y de tomar las medidas correctivas necesarias.

  4. Documentación: documenta a fondo los callbacks de tu API. Utiliza ejemplos y descripciones para dejar claro cómo deben implementar y gestionar los callbacks los clientes.

Herramientas y bibliotecas #

Varias herramientas y bibliotecas pueden ayudarte a implementar y probar los callbacks de OpenAPI:

  • Swagger Editor: este editor en línea te ayuda a escribir y validar tus definiciones OpenAPI.

  • Postman: Postman puede utilizarse para probar las URL de callback activándolas manualmente durante las pruebas.

  • Apiary: Apiary ofrece herramientas colaborativas para diseñar, probar y documentar API.

  • Mockoon: Mockoon permite configurar rápidamente un servidor simulado (mock) que puede simular URL de callback durante el desarrollo.

Conclusión #

Los callbacks de OpenAPI proporcionan un mecanismo sólido para habilitar la comunicación asíncrona entre clientes y servidores. Son una herramienta potente para construir sistemas reactivos basados en eventos y pueden reducir de forma significativa la complejidad de gestionar procesos de larga duración y actualizaciones en tiempo real.

Al comprender e implementar los callbacks de OpenAPI, puedes crear API más interactivas y receptivas que respondan a las crecientes exigencias de las aplicaciones modernas. Recuerda siempre seguir las buenas prácticas para garantizar la seguridad, la fiabilidad y una documentación clara, y así aprovechar al máximo esta potente característica.

Para obtener información más detallada sobre las especificaciones OpenAPI y los callbacks, consulta la documentación oficial de la especificación OpenAPI. ¡Feliz programación!

Última actualización: 29 de mayo de 2024.

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