Saltar al contenido

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

Introducción

Esta página te muestra cómo exponer un objeto de negocio como un punto final de API, cómo crear reglas de validación personalizadas para los datos enviados a ese punto final y cómo probar la configuración completa utilizando un cliente API externo.

Parte 1: Configurar el punto final de API

Esta sección cubre los pasos previos para exponer un objeto de negocio de la aplicación como una API.

1. Crear un proveedor de seguridad de clave API

Para autenticarte contra la API, primero necesitas un proveedor de seguridad. Sigue estos pasos:

  1. Selecciona IDE > Proveedores de Seguridad.

  2. En Autenticación de Usuario, haz clic en + Autenticación de Usuario. Se abre la página Proveedor.

  3. Configura el proveedor con estos ajustes:

    • Nombre: Ingresa un nombre descriptivo, como Clave API.

    • Tipo: Selecciona Clave API.

    • Habilitado: Selecciona para habilitar el proveedor.

  4. Haz clic en Guardar.

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

2. Definir un punto final de aplicación

A continuación, necesitas crear un punto de acceso para tu aplicación. Sigue estos pasos:

  1. Selecciona IDE > APIs REST.

  2. Haz clic en Gestionar Puntos Finales. Se abre la ventana emergente Puntos Finales de Aplicación mostrando las aplicaciones accesibles y sus puntos finales.

  3. Localiza la aplicación que deseas exponer y haz clic en su ícono Editar.

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

  5. Haz clic en el ícono (o en el botón Continuar) para guardar el nombre del punto final.

  6. Cierra la ventana emergente Puntos Finales de Aplicación. Una nueva entrada para el punto final aparece bajo Aplicación.

3. Publicar un punto final de objeto de negocio

Ahora puedes publicar un objeto de negocio específico (como una tabla) de tu aplicación. Sigue estos pasos:

  1. En la página de APIs REST, con tu aplicación seleccionada, haz clic en el botón + Recurso en la sección de Recursos. Se abre el popup de Recurso.

  2. Establece los siguientes valores:

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

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

  3. Haz clic en Guardar, luego cierra el popup de Recurso.

  4. Para encontrar la URL completa de tu nuevo endpoint, localiza tu aplicación en el panel de Aplicación y haz clic en el ícono Doc. Esto abre un informe que contiene la documentación del endpoint de la API.

  5. Desplázate por la documentación para encontrar la URL del endpoint del objeto de negocio que acabas de crear. Copia esta URL para usarla más tarde.

4. Generar una clave API específica para el usuario

El último paso de configuración es generar una clave API para un usuario, permitiéndole autenticarse. Sigue estos pasos:

  1. Selecciona IDE > Gestión de Usuarios.

  2. En Usuarios, haz clic en el ícono Abrir registro para el usuario al que deseas otorgar acceso a la API. Se abre el popup de Usuario.

  3. Expande la sección de Autenticación y confirma que el Tipo de Inicio de Sesión esté configurado como Interactivo.

  4. Selecciona Más > Claves. Se abre el popup de Claves.

  5. Haz clic en Crear. Se abre el popup de Generar Clave.

  6. Establece valores para lo siguiente:

    • Proveedor: Selecciona el proveedor de seguridad que creaste en el primer paso (por ejemplo, Clave API).

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

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

    Importante

    Asegúrate de haber copiado la clave antes de cerrar el popup de Generar Clave, ya que no se podrá mostrar nuevamente.

Parte 2: Crear una regla de validación personalizada

Esta sección cubre cómo crear y aplicar una regla personalizada para validar los datos entrantes antes de que se guarden. Este ejemplo crea una regla que impide que un registro se guarde si su Fecha Requerida está en el pasado.

1. Crear una regla de negocio para validación

Sigue estos pasos:

  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.

  4. En la página de 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 debería 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 necesita la regla. Para este ejemplo, agrega Order ID y Required Date.

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

  7. (Opcional) Haz clic en Validate.

2. Adjuntar la regla de validación a un evento

Para activar la regla, asóciala con un evento en el objeto de negocio. Sigue estos pasos:

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

  2. Haz clic en el ícono de Events para (en este ejemplo) Orders (Source). Se abre el popup de All Events.

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

  4. En Validations, haz clic en Register. Se abre el popup de Validation.

  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.

Parte 3: Prueba el endpoint de la API

Esta sección cubre cómo probar el endpoint utilizando un cliente API de terceros, como Postman, para asegurarse de que esté funcionando como se espera.

1. Configurar el Cliente de Prueba

Sigue estos pasos:

  1. En Postman, crea una nueva solicitud POST.

  2. En el campo de URL, pega la URL del endpoint que copiaste de la documentación de la API.

  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 API de usuario que copiaste anteriormente.

  4. Configura el cuerpo de la solicitud:

    • Selecciona la pestaña Body.

    • Selecciona el botón de opción Raw.

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

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

Sigue estos pasos:

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

    Ejemplo de registro de 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: La fecha requerida no puede estar en el pasado. El registro no se crea.

3. Probar el endpoint (caso de éxito)

Sigue estos pasos:

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

    Ejemplo de registro de éxito
    {
    "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.