Saltar al contenido

Exponer una operación como API REST en Jitterbit Studio

Introducción

API Manager te permite publicar una operación de Studio como un endpoint HTTP que cualquier llamante 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 activadas por eventos desde sistemas externos), consulta Activar una operación de Studio desde un webhook.

Patrón de diseño

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% 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: Abre la configuración de API

  1. En el lienzo de diseño, ubica 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: Configura 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 del servicio: Ingresa el segmento de ruta base utilizado en la URL del endpoint público (por ejemplo, customers). Este campo se rellena previamente con el nombre de la operación en notación camelCase. No se permiten espacios.

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

  4. Haz clic en Siguiente.

Paso 3: Configura los parámetros

En el paso Parámetros, 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 se complete la operación 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: Configura el endpoint del servicio

En el paso Servicios, define cómo los llamantes acceden a la operación:

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

  2. Ruta: Ingresa la subruta anexada a la URL base (por ejemplo, /records o /submit).

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

    • Variable del sistema: El cuerpo de respuesta es el valor asignado a $jitterbit.api.response en la operación. Utiliza esto en la mayoría de los casos, ya que brinda control total sobre el contenido de respuesta y el código de estado. Consulta la Parte 2 para obtener detalles.
    • Objetivo 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 se complete la operación. Utiliza esto para operaciones de larga duración "dispara y olvida" donde el llamante 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 Asignar junto a él.

  2. Para crear un perfil nuevo, 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 máquina a máquina. Para API orientadas al usuario que requieren identidad, usa OAuth 2.0.

    Consejo

    Dejar el endpoint sin asignar un perfil de seguridad 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 el consumidor de la API.

    Nota

    Una API publicada cuenta como una URL de API contra tu asignación de suscripción a Harmony. Guarda como Borrador si prefieres completar la configuración antes de hacer el endpoint 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 plano:

    <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 está establecida antes de que la operación se complete, API Manager devuelve una respuesta 200 OK vacía.

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 que publicaste.

  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 la solicitud se recibió y la operación se completó correctamente.

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