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 en los recursos. App Builder permite a los desarrolladores publicar objetos de datos como recursos REST. Los consumidores pueden realizar operaciones en dichos recursos que se traducen en invocaciones de eventos de objetos de datos.

Aplicaciones como servicios web

El ambiente de diseño de App Builder se organiza en torno al concepto de aplicación. Si bien las aplicaciones suelen describir 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.
A los grupos se les conceden privilegios sobre una aplicación.

App Builder amplía el concepto de aplicación para incluir servicios web. En concreto, los desarrolladores pueden definir un extremo para una aplicación. Por ejemplo, el extremo de la aplicación Ventas podría ser ventas. El URI correspondiente podría ser similar a esto:

https://example.com/App Builder/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 de esa colección.

Al igual que el propio servicio, el desarrollador determina el extremo del objeto de datos. Por ejemplo, el objeto de datos Clientes podría tener un extremo de clientes. En ese caso, el URI correspondiente podría ser similar a este:

https://example.com/App Builder/rest/v1/sales/customersEl URI de un elemento específico (fila) podría verse así:
https://example.com/App Builder/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1La clave principal aparece en la ruta URI.

Las claves principales compuestas se pueden especificar separándolas con una coma:

https://example.com/App Builder/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 de una colección. Esto se asigna al evento Filter. - POST /colección: Agrega un elemento a la colección. Esto se asigna al evento Insertar. GET /collection/item: recupera un solo elemento de la colección. Esto se asigna al evento Filter. POST /collection/item: Actualiza un elemento de la colección. Esto se asigna al evento Update. DELETE /colección/elemento: Elimina un elemento de la colección. Esto se asigna 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. Actualmente, App Builder no admite esta operación. - OPCIONES - El método OPCIONES permite a los consumidores determinar qué métodos son compatibles. PUT (colección o artículo): El método PUT permite a los consumidores crear o actualizar un artículo (al acceder a la colección). Sin embargo, dado que PUT es idempotente, debe incluir todos los campos. Esto limita su utilidad en muchos casos. PATCH: El método PATCH permite a los consumidores actualizar parte de un elemento. Actualmente, esto se realiza mediante un POST. Normalmente, PATCH utiliza un formato específico para cada parche, lo que complica la despliegue.

No se pueden publicar todos los eventos de App Builder:

Nuevo: El evento "Nuevo" de App Builder crea una fila no persistente y aplica los valores predeterminados. Los consumidores no pueden invocar el evento "Nuevo". Cambio: Las interacciones con la interfaz de usuario invocan un pseudoevento que ejecuta valores predeterminados y validaciones sin conservar los 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 se pueden asignar 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 no tienen estado.
Los Extremos 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 la modifica. Las operaciones DELETE son inseguras, pero idempotentes. Sin embargo, mientras que la primera solicitud (correcta) para eliminar un elemento devolverá un código de estado 200, la segunda solicitud devolverá un código de estado 404. Las operaciones POST no son seguras ni idempotentes. Por ello, pueden contener datos parciales.
Los códigos de estado HTTP indican si ocurrió un error. Los tipos de medios se utilizan para la negociación de contenido. Sin embargo, actualmente App Builder solo admite JSON (application/json) y UTF-8.

App Builder no cumple con todos los principios RESTful:

Las respuestas de los recursos se encapsulan 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 funciones:

Paginación mediante $offset y $limit Parámetros. El límite predeterminado es 10; el límite máximo es 100.
Ordenación mediante $sort parámetro. El $sort El parámetro puede tomar una lista de nombres de campo delimitada por comas. Añada un guion (-) al nombre del campo para ordenarlo en orden descendente. Por ejemplo, la especificación de ordenación $sort=-country,companyName Ordenaría la colección por país, de forma descendente, y por nombre de empresa, de forma ascendente.
Selección mediante un $fields parámetro. El $fields El parámetro puede tomar una lista delimitada por comas de nombres de campos (por ejemplo, $fields=customerId,country). Especifique el asterisco (*) para recuperar todos los campos de recursos (p. ej. $fields=*).
Búsqueda por palabra clave a través de un $q parámetro. El $q El parámetro toma una cadena e intenta compararla con los valores de las columnas. Se devolverá cualquier fila de la tabla que tenga al menos un valor de columna que contenga el parámetro $q como subcadena (p. ej. $q=miamiTenga en cuenta que la coincidencia no distingue entre mayúsculas y minúsculas.
Filtrado mediante comparaciones de igualdad simples. Para limitar los resultados, especifique el nombre y el valor del campo (p. ej. countryId=USA).
Contar mediante el $count Parámetro. De forma predeterminada, App Builder no devolverá un recuento total del número de elementos de la colección. Para incluir el recuento, añada el parámetro count (p. ej. $count=true).

Convenciones para parámetros:

Los parámetros que hacen referencia a campos de recursos no llevan prefijo.
Los parámetros que operan en la propia colección llevan el símbolo 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 message (definido en el IDE) y la gravedad de la validación ("error", "advertencia", "información").

Si desea omitir una advertencia, incluya el validationIds proporcionado como el valor de un encabezado X- App Builder -Ignore-Warnings en una nueva solicitud al extremo.

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 extremo y los mismos datos) deberá incluir la siguiente información de encabezado:

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

Problemas y limitaciones conocidos

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