Publicar una aplicación de Jitterbit App Builder como un endpoint de API REST

Descripción general

App Builder permite publicar los datos de una aplicación como una API REST, para que sistemas externos puedan leerlos y escribirlos usando una clave de API para autenticación, en lugar de crear una integración personalizada para cada consumidor. Esta página recorre un ejemplo completo: exponer una tabla customers de una aplicación Northwinds como un recurso REST, luego generar una clave de API que un usuario específico pueda usar para llamarla.

Los pasos son:

• Paso 1: Configurar un proveedor de seguridad de clave de API
  Crear el proveedor de seguridad contra el cual se autentican los llamadores.

• Paso 2: Configurar un endpoint
  Asignar a la aplicación el segmento de ruta base utilizado en sus URLs de API REST.

• Paso 3: Publicar un recurso
  Exponer un objeto de negocio específico como un recurso del cual los llamadores pueden leer y escribir, y controlar lo que se devuelve.

• Paso 4: Configurar claves de API para usuarios
  Generar la credencial que un usuario específico utiliza para autenticarse.

Paso 1: Configurar un proveedor de seguridad de clave de API

Para asegurar la API REST, primero se necesita un proveedor de seguridad de clave de API, que App Builder utiliza para validar la clave que presenta cada llamador:

1. Seleccionar IDE > Security Providers.

2. Hacer clic en + User Authentication desde el panel User Authentication. Se abre el diálogo Provider:

   

3. Asignar un Name al proveedor. Por ejemplo: API Key.

4. Seleccionar API Key como el valor de Type.

5. Marcar para seleccionar Enabled.

6. Hacer clic en Save.

Dependiendo del caso de uso, se pueden configurar cualquiera de las siguientes propiedades opcionales. Hacer clic en + Property desde el panel Properties para abrir el diálogo Properties:

• Para permitir escribir la clave de API en la barra de direcciones del navegador para pruebas (no recomendado más allá de pruebas, ya que no es muy seguro), seleccionar AllowApiKeyInQueryString como el Parameter e ingresar True como el Value, luego hacer clic en la marca de verificación para guardar el registro.

• Para permitir que la clave de API se pase sobre una conexión HTTP insegura (no recomendado), seleccionar AllowInsecureHttp como el Parameter e ingresar True para el Value, luego hacer clic en la marca de verificación para guardar el registro.

Paso 2: Configurar un endpoint

Se accede a la API REST de cada aplicación a través de un segmento de ruta base, su endpoint de aplicación. Seguir estos pasos para configurar uno:

1. Seleccionar IDE > REST APIs.

2. Hacer clic en el botón Manage Endpoints desde el panel Services. Se abre el diálogo Applications:

   

3. Hacer clic en el icono de edición para la aplicación que se desea configurar. Por ejemplo: Northwinds Design.

4. Ingresar el valor del endpoint en el campo Endpoint. Por ejemplo: northwinds.

5. Hacer clic en el botón Proceed, o en el icono de marca de verificación ; ambos guardan el valor del endpoint. La fila de la aplicación ahora muestra sus columnas Logging, Publish API Doc y Authentication.

6. (Desde App Builder 4.67. Si se utiliza una versión anterior, saltar al Paso 3.) Asociar los proveedores permitidos para autenticar las solicitudes de este endpoint:

   1. Hacer clic en el icono Authentication para la aplicación. Se abre el diálogo Authentication Providers:

1. Haz clic en + Autenticación. Se abre el diálogo Proveedor:

   

2. Selecciona uno de los proveedores de clave de API, HTTP o Servidor de autorización que hayas configurado. El campo Esquema se completa automáticamente con el esquema de ese proveedor, un nombre único que identifica al proveedor en URLs y documentos JSON. Opcionalmente, ingresa una Descripción y luego haz clic en Guardar. Repite los pasos 2 y 3 para cada proveedor adicional que desees permitir para autenticar las solicitudes de este endpoint.

3. Cierra el diálogo.

Paso 3: Publica un recurso

Con un endpoint de aplicación en su lugar, ahora puedes publicar un objeto de negocio específico como un recurso que los sistemas externos pueden llamar, controlando cuántos datos devuelve, su versión de esquema y qué eventos se exponen. Sigue estos pasos:

1. Selecciona IDE > API REST.

2. En el panel Servicios, localiza la aplicación y haz clic en el icono de chevron en su tarjeta. Se abre la página API REST para esa aplicación, mostrando sus propiedades de Servicio y Recursos en una sola vista.

3. En el panel Recursos, haz clic en + Recurso. Se abre el diálogo Recurso:

   

4. Establece los siguientes valores:

   • Tabla: Selecciona la tabla u objeto de negocio que expone este recurso. Una vez que se guarda el recurso, los iconos y junto a este campo se vuelven interactivos, llevándote a la página Definición de tabla de la tabla o a la página Generador de reglas del objeto de negocio (en App Workbench), respectivamente. Solo uno de los dos está disponible para un recurso determinado, dependiendo de si seleccionaste una tabla u un objeto de negocio.

   • Endpoint: Ingresa el segmento de ruta donde la API accede a este recurso.

   • Límite predeterminado de GET y/o Límite máximo de GET: Controla la cantidad de registros devueltos en llamadas GET a tu endpoint de API.

   • Compatibilidad: (Opcional, desde App Builder 4.51.) Controla cómo se comporta el recurso. La compatibilidad permite que App Builder introduzca nueva funcionalidad de endpoint entre versiones mientras preserva el comportamiento de los endpoints existentes para compatibilidad hacia atrás. Selecciona una de las siguientes opciones:

     • Versión 1: Usa el comportamiento REST original, en el que los eventos de Inserción no están precedidos por eventos de Nuevo. (Predeterminado para endpoints creados con App Builder 4.50 y anteriores.)

     • Versión 2: Usa un comportamiento REST mejorado, en el que los eventos de Nuevo y cualquier regla predeterminada se invocan antes de los eventos de Inserción. (Predeterminado para endpoints creados con App Builder 4.51.)

     • Versión 3: (Desde App Builder 4.52.) Igual que la versión 2, pero las APIs devuelven el valor lógico en lugar del valor de almacenamiento. Por ejemplo, los valores booleanos se devuelven como true o false en lugar de 1 o 0. (Predeterminado para endpoints creados con App Builder 4.52 y posteriores.)

   • Excluir de la documentación: (Opcional, desde App Builder 4.67.) Marca para omitir este recurso del documento OpenAPI publicado de la aplicación, incluso cuando la publicación de documentación está habilitada para la API REST en su conjunto.

   • Descripción: (Opcional.) Una descripción del recurso, incluida en el documento OpenAPI publicado de la aplicación.

5. Haz clic en Guardar.

6. La pestaña Nodos del diálogo enumera el nodo raíz implícito de este recurso, junto con cualquier nodo secundario que agregues. Haz clic en el icono de detalles de un nodo para abrir su diálogo Nodo: consulta Parámetros de nodo y Campos de nodo para controlar qué campos se incluyen en la respuesta de forma predeterminada, o Agregar un nodo secundario para anidar datos adicionales bajo este recurso.

7. (Desde App Builder 4.67.) En las propiedades del Service, expande el menú Más, luego haz clic en el botón Configurar autenticación. Se abre el mismo diálogo Proveedores de autenticación que en el Paso 2, mostrando los proveedores ya asociados con este endpoint y permitiéndote agregar otros si lo deseas:

   

   

Paso 4: Configurar claves de API para usuarios

Finalmente, genera una clave de API vinculada a un usuario específico, de modo que la identidad y los permisos de ese usuario se apliquen a cada solicitud realizada con esa clave:

1. Selecciona IDE > Gestión de usuarios.

2. Selecciona un usuario existente o crea un nuevo usuario para usar en la llamada de API.

   • El usuario debe estar configurado con el Tipo de inicio de sesión Interactivo.

   • El usuario no necesita tener Autenticación local.

3. En el registro del usuario seleccionado o creado, haz clic en el icono Claves.

4. Haz clic en Crear. Se abre el diálogo Generar clave:

   

5. Selecciona el proveedor de clave de API que creaste en el Paso 1 como el Proveedor, luego haz clic en Guardar. App Builder genera un valor de clave.

   Importante

   Copia la clave generada ahora. No se puede mostrar de nuevo una vez que abandones esta pantalla.

Para probar o configurar el uso de tus nuevos endpoints de API, utiliza la Clave de API del paso anterior, la información de URL base y Endpoint del documento de API, y el Nombre de los detalles del recurso.