API REST en Jitterbit App Builder

Descripción general

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 amplía 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 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.
• 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. 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.
• 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 y trata de 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, especifique 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, agregue 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 prefijados con 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").

Si desea omitir una advertencia, incluya 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 del encabezado:

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

Problemas conocidos y limitaciones

• Los campos binarios, como los archivos, no son compatibles actualmente.
• 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 el filtrado a través de comparaciones de igualdad simples.