REST APIs en Jitterbit App Builder

Introducción

App Builder proporciona dos formas principales de integrarse con APIs REST:

• Consumir (usando configuración manual o importando un documento OpenAPI) APIs REST externas para llevar datos a tus aplicaciones, o
• Publicar los datos de tu aplicación de 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 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 endpoint para una aplicación. Por ejemplo, el endpoint para una aplicación de Ventas podría ser sales. 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 un 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 endpoint del objeto de datos. Por ejemplo, el objeto de datos Clientes podría tener un endpoint de customers. 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 que corresponden 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 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 no admite actualmente 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 parche, complicando la implementación.

No todos los eventos de App Builder pueden ser publicados:

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

• Cambio: Las interacciones con la interfaz de usuario invocan un pseudoevento 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 puntos finales 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.

• Se utilizan tipos de medios para realizar la 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 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.

• Ordenamiento a través de un parámetro $sort. El parámetro $sort puede tomar una lista de nombres de campo 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 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 y trata de hacer coincidir con los valores de las columnas. Se devolverán 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 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).

• Conteo a través del parámetro $count. Por defecto, App Builder no devolverá un conteo total del número 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 en sí están precedidos por un 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).

Para omitir una advertencia, incluye los validationIds proporcionados como el valor de un encabezado X-Vinyl-Ignore-Warnings en una nueva solicitud al endpoint. Considera el ejemplo de respuesta 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"

Manejar respuestas POST

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

Vinculación con reglas CRUD de XP

Utiliza esto cuando la llamada POST sea parte de una operación CRUD donde la fuente de datos es una API externa y el destino 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 CRUD de XP 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 del POST, los datos de respuesta de la API se vuelven accesibles dentro de las tablas de respuesta autogeneradas 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 CRUD de XP para mapear directamente los campos de estas tablas de respuesta a las columnas en tu base de datos local para inserción o actualización.

Utiliza un controlador de éxito

Usar un controlador de éxito ofrece mayor flexibilidad para procesar respuestas de 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 función caller().

• 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 mediante comparaciones de igualdad simples.