API REST en Jitterbit App Builder

Introducción

App Builder proporciona dos formas principales para integrar API REST:

• Consumir (usando configuración manual o importando un documento OpenAPI) API REST externas para traer datos a tus aplicaciones, o
• Publicar los datos de tu aplicación App Builder como una API REST para que otros sistemas los consuman.

Conceptos y principios

Aplicaciones como servicios web

El entorno de diseño de App Builder se organiza alrededor del concepto de una aplicación. Aunque las aplicaciones típicamente describen una interfaz de usuario, tienen varias propiedades que también son aplicables a los servicios web:

• Las aplicaciones proporcionan acceso a múltiples fuentes de datos.

• Se otorgan privilegios de grupo a una aplicación.

App Builder extiende el concepto de una aplicación para incluir servicios web. Específicamente, los desarrolladores tienen la capacidad de definir un endpoint para una aplicación. Por ejemplo, el endpoint para una aplicación de Ventas podría ser sales. El URI correspondiente podría verse así:

https://example.com/Vinyl/rest/v1/sales

Objetos de datos como recursos

El principio organizador de REST es el concepto de un recurso. Los recursos pueden representar una colección de elementos o un elemento único. En términos de App Builder, un objeto de datos se representa como una colección con filas individuales representadas como elementos en esa colección.

Como el servicio en sí, el desarrollador determina el endpoint del objeto de datos. Por ejemplo, el objeto de datos Clientes podría tener un endpoint de customers. En ese caso, el URI correspondiente podría verse así:

https://example.com/Vinyl/rest/v1/sales/customers

El URI para un elemento específico (fila) podría verse así:

https://example.com/Vinyl/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

La clave principal aparece en la ruta del URI.

Se pueden especificar claves primarias compuestas separando las claves con una coma:

https://example.com/Vinyl/rest/v1/sales/customers/abc,def

Eventos como métodos HTTP

REST define un conjunto de operaciones correspondientes a métodos HTTP. La API REST de App Builder admite los siguientes métodos HTTP:

• GET /collection: Recupera los elementos dentro de una colección. Esto se asigna al evento Filtro.

• POST /collection: Agrega un elemento a la colección. Esto se asigna al evento Insertar.

• GET /collection/item: Recupera un elemento único de la colección. Esto se asigna al evento Filtro.

• POST /collection/item: Actualiza un elemento en la colección. Esto se asigna al evento Actualizar.

• DELETE /collection/item: Elimina un elemento de la colección. Esto se asigna al evento Eliminar.

La API REST de App Builder actualmente no admite los siguientes métodos HTTP:

• HEAD: El método HEAD permite a los consumidores recuperar los encabezados de respuesta HTTP. Por el momento, App Builder no admite esta operación.

• OPTIONS: El método OPTIONS permite a los consumidores determinar qué métodos se admiten.

• PUT (colección o elemento): El método PUT permite a los consumidores crear un elemento (al dirigirse a la colección) o actualizar un elemento (al dirigirse al elemento). Sin embargo, como PUT es idempotente, debe incluir todos los campos. Esto limita su utilidad en muchos escenarios.

• PATCH: El método PATCH permite a los consumidores actualizar parte de un elemento. Actualmente se admite a través de un POST. Típicamente, PATCH usa un formato específico de patch, complicando la implementación.

No todos los eventos de App Builder se pueden publicar:

• Nuevo: El evento Nuevo de App Builder crea una fila no persistente, aplicando cualquier valor predeterminado. Los consumidores no pueden invocar el evento Nuevo.

• Change: Las interacciones con la interfaz de usuario invocan un pseudo-evento que ejecuta valores predeterminados y validaciones sin persistir cambios. Los consumidores no pueden simular el evento Change.

• Eventos definidos por el usuario: Además de los eventos intrínsecos, los desarrolladores pueden definir sus propios eventos. Estos no se pueden asignar a los métodos de recursos estándar anteriores, pero se pueden invocar directamente a través de un patrón de URL dedicado. Para obtener más información, consulta Invocar eventos personalizados a continuación.

Invocar eventos personalizados

Además de los eventos estándar asignados a métodos HTTP anteriormente, la API REST de App Builder puede invocar un evento personalizado definido en un objeto de negocio. Esto ejecuta el evento de destino y cualquier acción asociada con él, como operaciones CRUD, notificaciones, procedimientos almacenados y reglas de negocio o validaciones.

Para invocar un evento personalizado, envía una solicitud POST con la siguiente sintaxis:

POST /{Resource}({EventName})/{RecordID}

Por ejemplo, invocar un evento llamado SendWelcomeEmail en un registro de cliente utiliza un URI como este:

https://example.com/Vinyl/rest/v1/sales/customers(SendWelcomeEmail)/9ce33474-8690-4a75-ab90-65caa6c3c24e

Principios de diseño RESTful

En la medida de lo posible, la API REST de App Builder sigue estos principios RESTful:

• Los servicios no tienen estado.

• Los puntos de conexión se modelan como recursos.

• Las operaciones GET son seguras. Una operación "segura" es aquella que no tiene efectos secundarios. Por ejemplo, recuperar una lista de clientes no cambia la lista de clientes.

• Las operaciones DELETE no son seguras, pero son idempotentes. Sin embargo, mientras que la primera solicitud (exitosa) para eliminar un elemento devolverá un código de estado 200, la segunda solicitud devolverá un 404.

• Las operaciones POST no son seguras ni idempotentes. Por esto, las operaciones POST pueden contener datos parciales.

• Los códigos de estado HTTP indican si ocurrió un error.

• Se utilizan tipos de medios para realizar negociación de contenido. Sin embargo, en este momento, App Builder solo admite JSON (application/json) y UTF-8.

App Builder no se adhiere a todos los principios RESTful:

• Las respuestas de recursos se envuelven en un sobre. Esto permite que App Builder incluya información adicional, como mensajes de eventos y resultados de validación.

• Las respuestas de recursos no son hipermedia: no incluyen enlaces a otros recursos.

Convenciones de URI REST

A nivel de colección, el método GET admite las siguientes características:

• Paginación a través de parámetros $offset y $limit. El límite predeterminado es 10; el límite máximo es 100.

• Ordenamiento a través de un parámetro $sort. El parámetro $sort puede tomar una lista de nombres de campos delimitada por comas. Prefija el nombre del campo con un guion (-) para ordenar el campo en orden descendente. Por ejemplo, la especificación de ordenamiento $sort=-country,companyName ordenaría la colección por country en orden descendente y companyName en orden ascendente.

• Selección a través de un parámetro $fields. El parámetro $fields puede tomar una lista de nombres de campos delimitada por comas (por ejemplo, $fields=customerId,country). Utiliza un asterisco (*) para recuperar todos los campos de recursos (por ejemplo, $fields=*).

• Búsqueda por palabra clave a través de un parámetro $q. El parámetro $q toma una cadena e intenta coincidir con los valores de las columnas. Se devolverán todas las filas de la tabla que tengan al menos un valor de columna que contenga el parámetro $q como subcadena (por ejemplo, $q=miami). La coincidencia no distingue mayúsculas de minúsculas.

• Filtrado mediante comparaciones de igualdad simple. Para limitar los resultados, especifica el nombre del campo y el valor (por ejemplo, countryId=USA).

• Conteo mediante el parámetro $count. Por defecto, App Builder no devuelve un conteo total de elementos dentro de la colección. Para incluir el conteo, añade el parámetro count (por ejemplo, $count=true).

Convenciones para parámetros:

• Los parámetros que hacen referencia a campos de recursos no llevan prefijo.

• Los parámetros que operan sobre la colección misma llevan prefijo de signo de dólar ($).

Validación

Un evento puede devolver uno o más errores, advertencias o resultados de validación informativa como parte de la respuesta. Cada validación incluirá un validationId, un message (definido en el IDE) y la severity de la validación (error, advertencia, información).

Para omitir una advertencia, incluye los validationIds proporcionados como valor de un encabezado X-Vinyl-Ignore-Warnings en una nueva solicitud al endpoint. Considera la respuesta de ejemplo a continuación:

{
  "item": {
    "contactId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
    "name": "Company Name"
  },
  "message": null,
  "validations": [
    {
      "validationId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
      "message": "32 emails will be sent, are you sure?",
      "severity": "warning"
    },
    {
      "validationId": "6bad40b7-2504-4243-9e90-100bcc7bfd13",
      "message": "No subject was provided, use default?",
      "severity": "warning"
    }
  ],
  "status": 400
}

Para omitir la advertencia que contiene esta respuesta, una nueva solicitud (al mismo endpoint y con los mismos datos) necesitaría incluir la siguiente información de encabezado:

X-Vinyl-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32","6bad40b7-2504-4243-9e90-100bcc7bfd13"

Gestionar respuestas POST

Hay dos formas de capturar y procesar los datos devueltos por una llamada POST: vinculación con reglas XP CRUD o uso de un manejador de éxito.

Vinculación con reglas XP CRUD

Utiliza esto cuando la llamada POST es parte de una operación CRUD donde la fuente de datos es una API externa y el destino es una base de datos local administrada por App Builder.

• Contexto: Cuando la respuesta de una llamada POST a una API externa necesita insertarse en una base de datos local.

• Configuración:

  • Registra una regla XP CRUD en una acción dentro de App Builder.

  • Pasa los parámetros necesarios para la llamada POST, asignándolos a campos correspondientes en tu API externa.

• Acceso a datos de respuesta:

  • Tras la ejecución exitosa de POST, los datos de respuesta de la API se vuelven accesibles dentro de tablas de respuesta generadas automáticamente en App Builder.

  • Dentro de tu regla, puedes unirte a estas tablas de respuesta utilizando los campos id y parent_id generados por el sistema.

• Procesamiento: Utiliza la funcionalidad XP CRUD para asignar directamente campos de estas tablas de respuesta a columnas en tu base de datos local para inserción o actualización.

Usar un manejador de éxito

Usar un manejador de éxito ofrece mayor flexibilidad para procesar respuestas de API con lógica personalizada que puede no implicar asignación directa a base de datos.

• Implementación:

  • Adjunta un manejador de éxito a la acción que inicia la llamada POST.

  • Recupera los datos de respuesta de la API dentro del manejador de éxito utilizando la función caller().

• Procesamiento: Implementa lógica personalizada dentro del manejador de éxito para analizar, manipular o enrutar los datos de respuesta según los requisitos de tu aplicación.

Problemas conocidos y limitaciones

• Los campos binarios como archivos no son actualmente compatibles.

• El único tipo de contenido compatible es JSON (application/json).

• La única codificación de texto compatible es UTF-8.

• Las colecciones están limitadas a devolver 100 elementos a la vez.

• Las claves primarias compuestas no pueden contener comas.

• Solo se admite filtrado mediante comparaciones de igualdad simple.