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 API REST y controlar lo que se guarda en él: 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 API de terceros. El ejemplo utilizado en toda la documentación 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 API
    Crea el proveedor de seguridad, el punto final de la aplicación y el punto final del objeto de negocio necesarios para exponer datos como API REST, luego genera una clave para que un usuario específico pueda autenticarse contra él.

  • Crear una regla de validación personalizada
    Agrega una regla de negocio que valide los datos entrantes antes de guardarse y adjúntala al evento de guardado del punto final.

  • Probar el punto final de API
    Usa 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 API

Antes de que 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 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 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. Haz clic en + Security Provider. Se abre la página Provider:

    Página Provider

  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

La API REST de cada aplicación se alcanza 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 que muestra las aplicaciones accesibles y sus puntos finales:

    Diálogo Application Endpoints

  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. Aparece una nueva entrada para el punto final en Services.

Paso 3: Publica 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 usuarios 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 de recurso

  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: Publica un recurso en Publica tu 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 Data objects as resources para el patrón URI exacto.

Paso 4: Genera una clave de API específica del usuario

Finalmente, genera una clave de API vinculada a un usuario específico, para 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 del 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é establecido 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 pruebas.

    Importante

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

Crea 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. Este ejemplo crea una regla que impide 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: Crea 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 Rule Builder:

    Generador de reglas

  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: Adjuntar 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 de (en este ejemplo) Orders (Source). Se abre el diálogo All Events.

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

  4. En 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 que se mostrará cuando la validación falle, como The required date cannot be in the past.

  7. Haz clic en Save.

Probar 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: Configurar 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 opción Raw.

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

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

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

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

    Registro de fallo de ejemplo
    {
    "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: Probar el endpoint (caso exitoso)

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.

    Registro de éxito de ejemplo
    {
    "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 correctamente.