API REST en Jitterbit App Builder

Introducción

REST es un estilo arquitectónico de servicios web. REST define un conjunto de operaciones sin estado que se pueden realizar sobre recursos. App Builder permite a los desarrolladores publicar objetos de datos como recursos REST. Los consumidores pueden realizar operaciones sobre esos recursos que se traducen en invocaciones de eventos de objetos de datos.

Aplicaciones como servicios web

El entorno de diseño de App Builder está organizado en torno al concepto de una aplicación. Aunque las aplicaciones típicamente describen una interfaz de usuario, las aplicaciones 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 a un grupo para 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 punto final para una aplicación. Por ejemplo, el punto final para la aplicación de Ventas podría ser ventas. La 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 "recurso". Los recursos pueden representar una colección de elementos o un solo elemento. 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.

Al igual que el servicio en sí, el desarrollador determina el punto final del objeto de datos. Por ejemplo, el objeto de datos Clientes podría tener un punto final de clientes. En cuyo caso, la URI correspondiente podría verse así:

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

La 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 primaria aparece en la ruta de la URI.

Las claves primarias compuestas se pueden especificar 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 los 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 mapea al evento Filter.
POST /collection: Agrega un elemento a la colección. Esto se mapea al evento Insert.
GET /collection/item: Recupera un solo elemento de la colección. Esto se mapea al evento Filter.
POST /collection/item: Actualiza un elemento en la colección. Esto se mapea al evento Update.
DELETE /collection/item: Elimina un elemento de la colección. Esto se mapea al evento DELETE.

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. En este momento, App Builder no admite esta operación.
OPTIONS: El método OPTIONS permite a los consumidores determinar qué métodos son compatibles.
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, dado que 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. Esto se admite actualmente a través de un POST. Típicamente, PATCH utiliza un formato específico de parches, complicando la implementación.

No todos los eventos de App Builder pueden ser publicados:

Nuevo: El evento Nuevo de App Builder crea una fila no persistente, aplicando cualquier valor predeterminado. Los consumidores no pueden invocar el evento Nuevo.
Cambio: 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 Cambio.
Eventos definidos por el usuario: Además de los eventos intrínsecos, los desarrolladores pueden definir sus propios eventos. Actualmente, estos no pueden ser mapeados a métodos de recursos.

Principios de diseño RESTful

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

Los servicios son sin estado.
Los endpoints 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 son inseguras, pero 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. Debido a esto, las operaciones POST pueden contener datos parciales.
Los códigos de estado HTTP indican si ocurrió un error.
Los tipos de medios se utilizan para realizar la negociación de contenido. En este momento, sin embargo, App Builder solo admite JSON (application/json) y UTF-8.

App Builder no se adhiere a todos los principios RESTful:

Las respuestas de recursos están envueltas 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 los parámetros $offset y $limit. El límite predeterminado es 10; el límite máximo es 100.
Ordenación 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 ordenación $sort=-country,companyName ordenaría la colección por país, 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). Especifique el asterisco (*) para recuperar todos los campos del recurso (por ejemplo, $fields=*).
Búsqueda por palabra clave a través de un parámetro $q. El parámetro $q recibe una cadena e intenta hacer coincidir con los valores de las columnas. Cualquier fila de la tabla que tenga al menos un valor de columna que contenga el parámetro $q como subcadena será devuelta (por ejemplo, $q=miami). Tenga en cuenta que la coincidencia no distingue entre mayúsculas y minúsculas.
Filtrado a través de comparaciones de igualdad simples. Para limitar los resultados, especifica el nombre del campo y el valor (por ejemplo, countryId=USA).
Contar a través del parámetro $count. Por defecto, App Builder no devolverá un conteo total de la cantidad de elementos dentro de la colección. Para incluir el conteo, añade el parámetro de conteo (por ejemplo, $count=true).

Convenciones para parámetros:

Los parámetros que se refieren a campos de recursos no tienen prefijo.
Los parámetros que operan sobre la colección misma tienen un prefijo de signo de dólar ($).

Validación

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

Si deseas omitir una advertencia, incluye los validationIds proporcionados como el valor de un encabezado X-Vinyl-Ignore-Warnings en una nueva solicitud al endpoint.

Por ejemplo, para la siguiente respuesta:

{
  "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
}

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"

Manejo de respuestas POST

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

Vinculación con reglas XP CRUD

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

Contexto: Cuando la respuesta de una llamada POST de una API externa necesita ser insertada 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, mapeándolos a los campos correspondientes en tu API externa.
Accediendo a los datos de respuesta:
- Tras la ejecución exitosa de un 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 mapear directamente los campos de estas tablas de respuesta a columnas en tu base de datos local para inserción o actualización.

Usar un controlador de éxito

Usar un controlador de éxito ofrece mayor flexibilidad para procesar respuestas de la API con lógica personalizada que puede no involucrar un mapeo directo a la base de datos.

Implementación:
- Adjunta un controlador de éxito a la acción que inicia la llamada POST.
- Recupera los datos de respuesta de la API dentro del controlador de éxito utilizando la caller() function.
Procesamiento: Implementa lógica personalizada dentro del controlador de éxito para analizar, manipular o dirigir los datos de respuesta de acuerdo con los requisitos de tu aplicación.

Problemas conocidos y limitaciones

Los campos binarios como archivos no son actualmente compatibles.
El único tipo de contenido soportado es JSON (application/json).
La única codificación de texto soportada 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 el filtrado a través de comparaciones de igualdad simples.