API REST

Descripción General

REST es un estilo arquitectónico de servicio 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 esos recursos que se traducen en invocaciones de eventos de objetos de datos.

Aplicaciones Como Servicios Web

El App Builder el ambiente de diseño se organiza en torno al concepto de aplicación. Aunque 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 tienen la capacidad de 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 tener este aspecto:

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. App Builder en términos generales, 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 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 verse así:

https://example.com/App Builder/rest/v1/sales/customersLa URL de un elemento (fila) específico podría verse así:
https://example.com/App Builder/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

La 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 los métodos HTTP. App Builder la API REST de admite los siguientes métodos HTTP:

GET /collection: recupera los elementos de una colección. Esto se asigna al evento Filter.
POST /collection: 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 /collection/item: elimina un elemento de la colección. Esto se asigna al evento DELETE.

App Builder la API REST de 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.
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 un artículo (al dirigirse a la colección) o actualizar un artículo (al dirigirse al artículo). 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. Actualmente, esto se realiza mediante un POST. Normalmente, PATCH utiliza un formato específico del parche, lo que complica la despliegue.

No todos App Builder los eventos se pueden publicar:

Nuevo - App Builder el evento New crea una fila no persistente y aplica los valores predeterminados. Los consumidores no pueden invocar el evento New.
Change: las interacciones con la IU invocan un pseudoevento que ejecuta valores predeterminados y validaciones sin mantener los 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 se pueden asignar a métodos de recursos.

Principios de Diseño RESTful

En la medida de lo posible, App Builder la API REST de 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 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 este motivo, pueden contener datos parciales.
Los códigos de estado HTTP indican si se produjo un error.
Los tipos de medios se utilizan para realizar la negociación de contenido. Sin embargo, por el momento, App Builder solo admite JSON (application/json) y UTF-8.

App Builder no se adhiere a todos los principios RESTful:

Las respuestas de los recursos se envuelven en un sobre. Esto permite App Builder para incluir 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 un $sort parámetro. El $sort el parámetro puede tomar una lista de nombres de campo delimitada por comas. Anteponga un guión (-) al nombre del campo 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, 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 hacerla 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). Tenga 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 a través de la $count parámetro. Por defecto, App Builder no devolverá un recuento total de la cantidad de elementos dentro de la colección. Para incluir el recuento, agregue el parámetro de recuento (por ejemplo, $count=true).

Convenciones para parámetros:

Los parámetros que hacen referencia a campos de recursos no tienen prefijo.
Los parámetros que operan en la colección en sí tienen como prefijo 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 X-App Builder encabezado -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.