Consumir APIs REST externas en Jitterbit App Builder

Introducción

Esta guía ofrece una visión general de cómo conectarse y consumir APIs REST externas como fuentes de datos dentro de App Builder. La configuración del servidor de fuente de datos REST se utiliza en todos los puntos finales REST.

Configurar y usar una fuente de datos REST implica estas etapas principales:

1. Crear un servidor de fuente de datos REST: Establecer la conexión inicial a la URL base de la API REST.

2. Configurar y agregar puntos finales: Definir los puntos finales específicos de la API a los que se desea acceder, incluidos sus parámetros, encabezados y métodos.

3. Usar Objetos REST para una integración completa: Abstractar la API configurada en un Objeto REST para operaciones CRUD sin problemas e integración de UI.

A lo largo de esta guía, se utiliza la API de datos de acciones gratuita Alpha Vantage como un ejemplo práctico.

Crear un servidor de fuente de datos REST

Para crear un servidor de datos REST, sigue estos pasos:

1. Selecciona IDE > Servidores de Datos.

2. Haz clic en el botón + Servidor.

3. En la sección Configuración del Servidor, establece los siguientes campos:

   • Nombre del Servidor: Ingresa un nombre descriptivo para el servidor. Para nuestro ejemplo, usa Alpha Vantage.

   • Tipo: Selecciona API REST.

   • URL: Ingresa la URL base proporcionada en la documentación de tu API. Para Alpha Vantage, esta es https://www.alphavantage.co/.

     Nota

     Los puntos finales específicos se configuran en un paso posterior.

   • Tipo de Contenido de Solicitud y Tipo de Contenido de Respuesta: Selecciona los tipos de contenido de solicitud y respuesta. Típicamente, esto es JSON.

4. (Opcional) Expande la sección Configuración de Seguridad si tu API requiere autenticación de nombre de usuario/contraseña a nivel de servidor.

   Consejo

   La mayoría de las APIs REST, incluida Alpha Vantage, utilizan una clave de API en el encabezado o en la cadena de consulta. Esto se configura en la siguiente sección.

5. (Opcional) Descripción: Ingresa una descripción para este servidor.

6. Haz clic en el botón Guardar, luego cierra el diálogo. Deberías ver tu nuevo servidor de datos REST en la lista.

Configurar y agregar puntos finales REST

Después de crear el servidor de origen de datos, debes configurar sus parámetros y definir los puntos finales de la API a los que deseas acceder.

Configurar parámetros comunes (encabezados y cadenas de consulta)

Puedes definir parámetros que se aplican a todos los puntos finales en el servidor, como para la autenticación. La mayoría de los servicios REST requieren que pases una clave de API.

Para configurar un parámetro común, sigue estos pasos:

1. En la lista de Servidores de Datos, haz clic en el botón Abrir registro para tu nuevo servidor de datos REST.

2. En el popup de Servidor, bajo Configuración del Servidor, haz clic en el ícono Puntos finales.

3. En el panel de Parámetros del Servicio Web, haz clic en el botón + Parámetro. Aparece una nueva fila.

4. Establece los valores según los requisitos de tu API. Para nuestro ejemplo de Alpha Vantage, necesitamos agregar la clave de API como un parámetro de cadena de consulta:

   • Tipo: Selecciona Consulta.

   • Nombre: Ingresa el nombre del parámetro. Para este ejemplo, usa apikey. El nombre debe coincidir con lo que espera la API.

   • Valor: Pega tu clave de API única.

   • Tipo de Uso: (Opcional) Selecciona un tipo de uso.

5. Haz clic en el ícono para guardar el parámetro.

Agregar un punto final REST

Una vez que tu servidor de datos REST ha sido configurado, puedes agregar puntos finales específicos de la API.

Para agregar un punto final, sigue estos pasos:

1. En el panel de Puntos finales, haz clic en el botón + Punto final. Aparece una nueva fila.

2. Establece los valores en la fila de la siguiente manera. Para nuestro ejemplo, crearemos un punto final para obtener una cotización de acciones global:

   • Nombre: Dale al punto final un nombre descriptivo. Para este ejemplo, usa global_quote. Este nombre se utiliza para identificar la tabla de datos resultante en App Builder.

   • Punto final: Ingresa la parte de la URL que especifica el recurso. Para este ejemplo, se obtiene una cotización global ingresando lo siguiente, que incluye un marcador de posición {{ticker}} para un parámetro definido a continuación:

query?function=GLOBAL_QUOTE&symbol={{ ticker }}

• Método: Selecciona el método HTTP. Para este ejemplo, selecciona GET.

• Haz clic en el ícono para guardar el endpoint.

Definir parámetros específicos del endpoint

Ahora agrega un parámetro para el ticker de la acción a consultar:

1. En el panel de Parámetros del Servicio Web, haz clic en + Parámetro nuevamente.

2. Establece los valores de la siguiente manera:

   • Tipo: Selecciona Consulta.

   • Nombre: Ingresa un nombre para este parámetro. Para este ejemplo, ticker.

   • Valor: Déjalo en blanco, ya que queremos proporcionarlo dinámicamente.

   • Tipo de Uso: Selecciona Entrada.

   • Valor de Prueba: Ingresa AAPL (para Apple Corp.) con fines de prueba.

3. Haz clic en el ícono para guardar el parámetro.

Probar la conexión

Finalmente, prueba el endpoint para asegurarte de que tu configuración sea correcta.

1. En el panel de Endpoints, selecciona el endpoint global_quote recién creado.

2. Haz clic en Probar Conexión, luego en Proceder.

Si la configuración es correcta, aparece un mensaje "Prueba de conexión exitosa", y los datos devueltos de la API (la información para AAPL) se muestran en la sección de Resultados de Texto.

Tu endpoint de API ahora está conectado. App Builder crea automáticamente una tabla de datos llamada global_quote (del nombre del endpoint) en la fuente de datos Alpha Vantage, que ahora puedes usar para construir componentes de UI.

Alternativa: Importar desde un documento OpenAPI

Si tienes un documento OpenAPI (Swagger) para tu API REST, puedes importarlo para generar automáticamente endpoints. Consulta Importar un documento OpenAPI para obtener instrucciones detalladas.

Usar Objetos REST para una integración completa

Los Objetos REST permiten a los desarrolladores de App Builder utilizar APIs REST de manera similar a los objetos de datos de App Builder, habilitando operaciones completas de CRUD (Crear, Leer, Actualizar, Eliminar), eventos personalizados e integración avanzada de UI.

Para las API REST que admiten operaciones de estilo CRUD, configurar un Objeto REST es una forma sencilla de integrar una API con tu aplicación de App Builder.

Configurar puntos finales CRUD

Para una API REST de estilo CRUD, debes configurar puntos finales que permitan que los registros realicen operaciones de Crear, Leer, Actualizar y Eliminar. Esto generalmente implica configurar los siguientes puntos finales en tu fuente de datos REST:

Sigue los pasos en Agregar un punto final REST para cada operación CRUD que necesites, proporcionando el Nombre, Punto final, Método y cualquier Entrada de ejemplo requerida para los métodos POST o PUT.

Crear un Objeto REST

Una vez que tus puntos finales CRUD han sido configurados, puedes crear el Objeto REST.

1. Selecciona IDE > Servidores de datos.

2. Selecciona tu servidor de datos REST, luego haz clic en Abrir registro para la API REST. Se abre el popup de API REST.

3. En API REST, haz clic en Puntos finales.

4. En Servicio web, haz clic en Más > Super Objetos. Se abre el diálogo de Objetos REST.

5. Haz clic en + REST Object.

6. Ingresa un nombre para tu objeto REST (por ejemplo, Customers), luego haz clic en el ícono de guardar .

7. Haz clic en el ícono de editar lápiz , habilita Insertar, Actualizar y Eliminar según corresponda, luego haz clic nuevamente en el ícono de guardar .

Configurar y vincular el objeto REST

Después de crear el objeto REST, debes configurar su Single Comp y Many Comp y vincular las operaciones CRUD a tus endpoints.

1. Configurar Single y Many Comps: Abre el objeto REST y configura el Single Comp y Many Comp agregando las tablas apropiadas (por ejemplo, customers(get)/items) y columnas de tu endpoint de lectura.

2. Configurar Endpoints CRUD: Para cada operación CRUD (Eliminar, Insertar, Actualizar), selecciona el endpoint correspondiente que creaste y vincula los campos del objeto REST a los parámetros de entrada del endpoint.

Ahora deberías poder usar este objeto REST en la interfaz de usuario de tu aplicación, y agregar, eliminar o actualizar filas como si fuera una tabla nativa de App Builder.

Funciones avanzadas: Ordenamiento, paginación y filtrado

Los objetos REST también admiten funciones avanzadas de interacción con datos. Para habilitarlas, debes configurar parámetros específicos en tu fuente de datos REST con el Tipo de Uso correcto:

• Ordenamiento: Agrega un parámetro con el Tipo de Uso establecido en Request Sort. El nombre del parámetro debe coincidir con lo que tu API espera (por ejemplo, $sort).

• Paginación: Configura parámetros para Request Limit, Request Offset (o Request Page Number) y Request Count. También necesitas establecer el Tipo de Uso de la columna count en tu tabla de respuesta a Response Total Rows.

• Filtrado: Agrega un parámetro con el Tipo de Uso establecido en Request Filter (OData) para filtrado al estilo OData. El nombre del parámetro debe coincidir con lo que tu API espera (por ejemplo, $filter).