Saltar al contenido

Exponer una operación como API REST en Jitterbit Studio

Introducción

API Manager permite publicar una operación de Studio como un endpoint HTTP que cualquier usuario autorizado puede invocar bajo demanda. Una vez publicado, el endpoint acepta una solicitud HTTP, ejecuta la operación vinculada de forma sincrónica y devuelve el resultado de la operación como respuesta HTTP.

Este patrón es útil cuando un sistema externo o una herramienta interna necesita solicitar datos o activar procesamiento bajo demanda, por ejemplo una aplicación web que consulta registros de clientes, un sistema asociado que envía pedidos para procesamiento, o un panel interno que activa la generación de reportes.

Esta guía utiliza la opción integrada de Studio Publicar como API, que abre la configuración de API directamente desde la operación. Alternativamente, se puede lograr el mismo resultado desde la interfaz de API Manager (consulta API personalizada).

Esta guía asume lo siguiente:

  • Se configura una API personalizada y se publica en API Manager en el mismo entorno que el proyecto.
  • La operación que se expondrá como API ya está construida e implementada.

Para el patrón complementario (recibir notificaciones webhook impulsadas por eventos desde sistemas externos), consulta Activar una operación de Studio desde un webhook.

Patrón de diseño

flowchart LR A[Cliente API] -->|Solicitud HTTP| B[API Manager API personalizada] --> C[Operación de Studio] -->|Respuesta HTTP| A

Parte 1: Publicar la operación como API

Paso 1: Abrir la configuración de API

  1. En el lienzo de diseño, localiza la operación que deseas publicar.

  2. Haz clic en el icono del menú de acciones en la operación y selecciona Publicar como API.

    El panel de configuración de API se abre en la parte inferior del diseñador de proyectos.

    Nota

    Esta opción solo está disponible si la operación no tiene cambios sin implementar. Implementa la operación primero si la opción no está disponible.

Paso 2: Configurar el perfil de API

En el paso Perfil, ingresa los detalles básicos de la API:

  1. Nombre de API: Ingresa un nombre para identificación interna (por ejemplo, Customer Query API). Este nombre aparece en API Manager y en los registros de operaciones.

  2. Raíz de servicio: Ingresa el segmento de ruta base utilizado en la URL del endpoint público (por ejemplo, customers). Este campo se completa previamente con el nombre de la operación en formato camelCase. No se permiten espacios.

  3. Número de versión: Ingresa una cadena de versión (por ejemplo, v1). Esto se convierte en parte de la URL del endpoint.

  4. Haz clic en Siguiente.

Paso 3: Configurar ajustes

En el paso Ajustes, configura el comportamiento en tiempo de ejecución:

  1. Solo SSL: Déjalo habilitado. Esto requiere HTTPS y se recomienda para todos los endpoints de producción.

  2. Tiempo de espera: Establece el tiempo máximo que API Manager espera a que la operación se complete antes de devolver un error de tiempo de espera agotado. El valor predeterminado es 30 segundos; el máximo es 180 segundos.

  3. Registro detallado: Habilítalo durante el desarrollo para incluir datos de solicitud y respuesta en los registros de API. Desactívalo en producción para evitar archivos de registro grandes.

  4. Haz clic en Siguiente.

Paso 4: Configurar el endpoint de servicio

En el paso Servicios, define cómo los usuarios llegan a la operación:

  1. Método: Selecciona el método HTTP que utilizarán los usuarios. Para operaciones de lectura, selecciona GET. Para operaciones que aceptan un cuerpo de solicitud (envío de datos, creación de registros), selecciona POST.

  2. Ruta: Ingresa la subruta que se añade a la URL base (por ejemplo, /records o /submit).

  3. Tipo de respuesta: Selecciona cómo la operación devuelve su respuesta al usuario:

    • Variable del sistema: El cuerpo de la respuesta es el valor asignado a $jitterbit.api.response en la operación. Utiliza esto en la mayoría de los casos, ya que proporciona control total sobre el contenido de la respuesta y el código de estado. Consulta la Parte 2 para más detalles.
    • Destino final: La respuesta es el resultado de una actividad de respuesta de API al final de la cadena de operaciones. Utiliza esto cuando la operación ya termina con una actividad de respuesta de API.
    • Sin respuesta: API Manager devuelve un 202 Accepted vacío inmediatamente sin esperar a que la operación se complete. Utiliza esto para operaciones de larga duración sin respuesta donde el usuario no necesita un resultado.

  4. Haz clic en Siguiente.

Paso 5: Agregar un perfil de seguridad

En el paso Perfiles de seguridad, asigna al menos un perfil de seguridad para restringir el acceso al endpoint.

  1. Para usar un perfil existente, activa el botón de alternancia Asignar junto a él.

  2. Para crear un nuevo perfil, haz clic en Nuevo perfil de seguridad y sigue las indicaciones. La clave de API y la autenticación básica son las opciones más comunes para integraciones de máquina a máquina. Para las API orientadas al usuario que requieren identidad, usa OAuth 2.0.

    Consejo

    Dejar el endpoint sin un perfil de seguridad asignado lo hace públicamente accesible para cualquiera que tenga la URL. Siempre asigna un perfil de seguridad antes de publicar en producción.

  3. Haz clic en Siguiente.

Paso 6: Publicar

  1. En el paso Roles de usuario, opcionalmente restringe el acceso por rol de organización. Haz clic en Siguiente si no se necesita restricción de rol.

  2. Haz clic en Publicar.

    La API estará activa en cinco minutos. API Manager muestra la URL completa del endpoint en el formato https://<host>/<service-root>/<version>/<path>. Copia esta URL para compartirla con quien llame a la API.

    Nota

    Una API publicada cuenta como una URL de API en tu asignación de suscripción de Harmony. Guarda como Borrador en su lugar si deseas completar la configuración antes de poner el endpoint en activo.

Parte 2: Devolver una respuesta desde la operación

Cuando el Tipo de respuesta está configurado como Variable del sistema, la operación debe asignar el cuerpo de la respuesta a $jitterbit.api.response antes de completarse. Agrega un paso de script al final de la operación (o al final de la cadena de operaciones) para establecer este valor.

  • Devolver una respuesta JSON:

    <trans>
$jitterbit.api.response = JSONStringify($result_dict);
$jitterbit.api.response.status_code = 200;
</trans>

  • Devolver una respuesta de texto sin formato:

    <trans>
$jitterbit.api.response = "Processing complete";
$jitterbit.api.response.status_code = 200;
</trans>

  • Devolver una respuesta de error:

    <trans>
$err_response = Dict();
$err_response["error"] = "Record not found";
$jitterbit.api.response = JSONStringify($err_response);
$jitterbit.api.response.status_code = 404;
</trans>

Si $jitterbit.api.response no se establece antes de que se complete la operación, API Manager devuelve una respuesta vacía 200 OK.

Para obtener una lista completa de variables de API Jitterbit, consulta Variables de API Jitterbit.

Verificar la integración

  1. Implementa el proyecto si has realizado cambios desde la publicación.

  2. En API Manager, copia la URL del endpoint publicado desde la página APIs.

  3. Envía una solicitud de prueba al endpoint usando una herramienta como curl o Postman, incluyendo el encabezado de autorización apropiado para el perfil de seguridad que asignaste.

  4. Confirma que el cuerpo de la respuesta HTTP y el código de estado coincidan con los valores establecidos en la operación.

  5. Abre los registros de API en API Manager y los registros de operación en Studio para confirmar que se recibió la solicitud y que la operación se completó correctamente.

Para agregar autenticación a la operación misma (por ejemplo, para validar un JWT en un paso de script antes de procesar la solicitud), consulta Autenticar endpoints de API usando JWT.