Saltar al contenido

Configurar y validar objetos de negocio como puntos finales de API en Jitterbit App Builder

Descripción general

Esta página te guía a través de un flujo de trabajo completo para exponer datos de App Builder como una API REST y controlar qué se guarda en ella: configurar un objeto de negocio como un punto final que pueden llamar sistemas externos, agregar una regla de validación que rechace datos incorrectos antes de que se persistan, y probar todo con un cliente de API de terceros. El ejemplo que se usa en toda la página expone un objeto de negocio Order y agrega una regla que rechaza cualquier pedido cuya Required Date ya esté en el pasado.

Los pasos son:

  • Configurar el punto final de la API
    Crear el proveedor de seguridad, el punto final de la aplicación y el punto final del objeto de negocio necesarios para exponer datos como una API REST, luego generar una clave para que un usuario específico pueda autenticarse contra ella.

  • Crear una regla de validación personalizada
    Agregar una regla de negocio que valide los datos entrantes antes de que se guarden y adjuntarla al evento Save del punto final.

  • Probar el punto final de la API
    Usar Postman para confirmar que la regla de validación rechaza datos inválidos y que el punto final acepta datos válidos.

Configurar el punto final de la API

Antes de que los sistemas externos puedan leer o escribir datos a través de la API REST de App Builder, necesitas exponer un objeto de negocio específico como un punto final y configurar una forma para que los llamadores se autentiquen contra él. Esta sección cubre los pasos previos para hacer ambas cosas:

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

Para autenticar las solicitudes realizadas a tu nuevo punto final, primero necesitas un proveedor de seguridad de clave de API, que App Builder utiliza para validar la clave que presenta cada llamador. Sigue estos pasos:

  1. Selecciona IDE > Security Providers.

  2. En User Authentication, haz clic en + User Authentication. Se abre el diálogo Provider:

    provider dialog

  3. Configura el proveedor con estos ajustes:

    • Name: Ingresa un nombre descriptivo, como API Key.

    • Type: Selecciona API Key.

    • Enabled: Selecciona para habilitar el proveedor.

  4. Haz clic en Save.

  5. (Opcional) En Properties, haz clic en + Property para agregar y configurar parámetros opcionales para tu clave de API.

Paso 2: Definir un punto final de aplicación

Se accede a la API REST de cada aplicación a través de un segmento de ruta base, su punto final de aplicación. Define uno ahora si tu aplicación aún no tiene uno:

  1. Selecciona IDE > REST APIs.

  2. Haz clic en Manage Endpoints. Se abre el diálogo Application Endpoints mostrando las aplicaciones accesibles y sus puntos finales:

    Application Endpoints dialog

  3. Localiza la aplicación que deseas exponer y haz clic en su icono Edit.

  4. Ingresa un nombre para el punto final, como endpoint-example.

  5. Haz clic en el icono (o el botón Proceed) para guardar el nombre del punto final.

  6. Cierra el diálogo Application Endpoints. Una nueva entrada para el punto final aparece en Services.

Paso 3: Publicar un endpoint de objeto de negocio

Con un endpoint de aplicación en su lugar, ahora puedes publicar un objeto de negocio específico, como una tabla, como un recurso que los llamadores pueden leer y escribir:

  1. En el panel Services, haz clic en el icono de chevron en el tile de tu aplicación. Se abre la página REST API para esa aplicación.

  2. En el panel Resources, haz clic en + Resource. Se abre el diálogo Resource:

    Diálogo Resource

  3. Establece los siguientes valores:

    • Table: Abre el menú y selecciona la tabla que deseas exponer.

    • Endpoint: Ingresa un nombre para el endpoint de la tabla.

    Para una descripción completa de todos los campos, consulta Paso 3: Publicar un recurso en Publicar una aplicación Jitterbit App Builder como un endpoint REST API.

  4. Haz clic en Save, luego cierra el diálogo Resource.

  5. Para encontrar la URL completa de tu nuevo endpoint, combina la URL base de REST API de tu instancia con el endpoint de tu aplicación (del paso anterior) y el endpoint del recurso (de este paso). Consulta Objetos de datos como recursos para el patrón URI exacto.

Paso 4: Generar una clave API específica del usuario

Finalmente, genera una clave 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 > User Management.

  2. En Users, haz clic en el icono Open record para el usuario al que deseas otorgar acceso a la API. Se abre el diálogo User.

  3. Expande la sección Authentication y confirma que Login Type esté configurado en Interactive.

  4. Selecciona More > Keys. Se abre el diálogo Keys.

  5. Haz clic en Create. Se abre el diálogo Generate Key:

    Diálogo Generate Key

  6. Establece valores para lo siguiente:

    • Provider: Selecciona el proveedor de seguridad que creaste en Paso 1 (por ejemplo, API Key).

    • (Opcional) Description: Ingresa una descripción para esta clave.

  7. Haz clic en Save. App Builder genera automáticamente un valor para la clave. Copia el valor de clave generado para usarlo en las pruebas.

    Importante

    Asegúrate de haber copiado la clave antes de cerrar el diálogo Generate Key, ya que no se puede mostrar nuevamente.

Crear una regla de validación personalizada

Una regla de validación te permite rechazar datos incorrectos antes de que se guarden, en lugar de después del hecho. Este ejemplo crea una regla que evita que se guarde un registro si su Required Date está en el pasado, luego adjunta esa regla al evento Save del endpoint para que realmente se ejecute.

Paso 1: Crear una regla de negocio para validación

Las reglas de negocio validan datos de tabla usando condiciones de estilo SQL sobre sus columnas. Crea una ahora para definir la verificación que tu endpoint debe aplicar:

  1. Abre tu aplicación y selecciona App Workbench > Rules.

  2. Haz clic en By Table, luego selecciona la tabla que estás exponiendo (por ejemplo, Order).

  3. En Rules, haz clic en + Rule. Se abre el Rule Builder:

    Rule builder

  4. En la página Rule, configura las propiedades básicas de la regla:

    • Name: Ingresa un nombre descriptivo, como Validation: Date Not in Past.

    • Purpose: Selecciona Validation.

    • Target: La tabla ya debe estar seleccionada (por ejemplo, Order).

  5. Haz clic en Create.

  6. Configura la lógica de la regla:

    • Selecciona la pestaña Columns, luego agrega las columnas que la regla necesita. Para este ejemplo, agrega Order ID y Required Date.

  7. Selecciona la pestaña Where, luego agrega una cláusula para definir la condición de fallo. En este ejemplo, para verificar si la fecha requerida está en el pasado, agrega una condición donde Required Date es menor que o igual a Now().

  8. (Opcional) Haz clic en Validate.

Paso 2: Adjunta la regla de validación a un evento

Una regla de validación no se ejecuta por sí sola. Debes adjuntarla a un evento específico, en este caso Save, para que se ejecute cuando un registro esté a punto de guardarse:

  1. Desde App Workbench > Rules, con By Table seleccionado, selecciona la misma tabla (Order en este ejemplo).

  2. Haz clic en el icono Events para (en este ejemplo) Orders (Source). Se abre el diálogo All Events.

  3. En la fila Save, haz clic en Rule Event Detail.

  4. Bajo Validations, haz clic en Register. Se abre el diálogo Validation:

    Diálogo de validación

  5. Desde el menú Rule, selecciona la regla de validación que acabas de crear (Validation: Date Not in Past).

  6. Configura la acción de validación de la siguiente manera:

    • Binding: Selecciona Implicit.

    • Failure: Selecciona Fail on data returned.

    • Severity: Selecciona Error.

    • Message: Ingresa el mensaje de error a mostrar cuando la validación falle, como The required date cannot be in the past.

  7. Haz clic en Save.

Prueba el endpoint de API

Con el endpoint publicado y la regla de validación adjunta, confirma que todo funciona de extremo a extremo usando un cliente de API de terceros. Esta sección usa Postman, pero las mismas solicitudes funcionan con cualquier cliente HTTP capaz de enviar solicitudes JSON autenticadas.

Paso 1: Configura el cliente de prueba

Antes de enviar cualquier solicitud, configura Postman con la autenticación y el formato de cuerpo que tu endpoint espera:

  1. En Postman, crea una nueva solicitud POST.

  2. En el campo URL, pega la URL del endpoint que copiaste en el Paso 3 de la sección anterior.

  3. Configura la autorización:

    • Selecciona la pestaña Authorization.

    • Para Type, selecciona API Key.

    • Para Key, ingresa X-API-Key.

    • Para Value, pega la clave de API específica del usuario que copiaste en el Paso 4.

  4. Configura el cuerpo de la solicitud:

    • Selecciona la pestaña Body.

    • Selecciona el botón de radio Raw.

    • Desde el menú desplegable de formato, selecciona JSON.

Paso 2: Prueba la regla de validación (caso de fallo)

Primero, confirma que la regla de validación realmente bloquea datos incorrectos, enviando una solicitud que debería fallar:

  1. En el cuerpo JSON, pega un registro para activar el error de validación. En este ejemplo, usa una Required Date que esté en el pasado.

    Ejemplo de registro con fallo
    {
    "OrderID": 11255,
    "OrderDate": "2014-05-26T00:00:00",
    "RequiredDate": "2014-05-20T00:00:00",
    "ShippedDate": "2014-05-28T00:00:00",
    "ShipCost": 1000.50,
    "ShipName": "Test Site",
    "ShipAddress": "508 Main Street",
    "ShipCity": "Harwich",
    "ShipState": "MA",
    "ShipZip": "02630",
    "ShipCountry": "USA",
    "AddedOn": null,
    "AddedBy": null,
    "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
    "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
}

  2. Haz clic en Send.

  3. Revisa la respuesta. Deberías ver un error de validación con el mensaje personalizado que configuraste: The required date cannot be in the past. El registro no se crea.

Paso 3: Prueba el endpoint (caso de éxito)

Ahora confirma que el endpoint acepta datos válidos una vez que la misma condición de fallo ya no se aplica:

  1. En el cuerpo JSON, modifica los datos para que sean válidos. En este ejemplo, cambia RequiredDate a una fecha en el futuro.

    Ejemplo de registro exitoso
    {
    "OrderID": 11255,
    "OrderDate": "2014-05-26T00:00:00",
    "RequiredDate": "2114-05-20T00:00:00",
    "ShippedDate": "2014-05-28T00:00:00",
    "ShipCost": 1000.50,
    "ShipName": "Test Site",
    "ShipAddress": "508 Main Street",
    "ShipCity": "Harwich",
    "ShipState": "MA",
    "ShipZip": "02630",
    "ShipCountry": "USA",
    "AddedOn": null,
    "AddedBy": null,
    "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
    "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
}

  2. Haz clic en Send.

  3. Revisa la respuesta. Deberías ver un estado 200 OK, y el cuerpo de la respuesta no debería contener un error de validación.

  4. Para confirmar, navega a la tabla de datos en tu aplicación App Builder y verifica que el nuevo registro se haya creado exitosamente.