Recomendaciones de API REST en Jitterbit App Builder

Descripción general

Este documento proporciona orientación para los desarrolladores que buscan desplegar una API REST compatible con App Builder.

Para los fines de este documento, asumiremos que el desarrollador se centra en la creación de un servicio CRUD REST. Muchos de los principios utilizados en una API CRUD serán aplicables a otras APIs. Sin embargo, una API CRUD probablemente tendrá los requisitos más completos que interactuarán con App Builder (paginación, búsqueda, filtrado, etc.).

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:

Los cuerpos de solicitud y respuesta de 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.

Sobre

Los cuerpos de solicitud y respuesta de la API REST de App Builder se encapsulan en un sobre. Los sobres permiten enviar datos hacia y desde un extremo de la API fuera de la carga útil del extremo.

Sobre del cuerpo de la solicitud

El cuerpo de la solicitud de la API REST de App Builder contiene estas propiedades de sobre:

Nombre de la propiedad	Descripción
item	La carga útil del extremo.

Ejemplo JSON

{
  "item": {}
}

Sobre del cuerpo de la respuesta

El cuerpo de respuesta de la API REST de App Builder contiene estas propiedades de sobre:

Nombre de la propiedad	Descripción
message	El mensaje de éxito o fracaso del evento.
status	Este es el código de estado HTTP (duplicado).
validations	Una matriz de errores/advertencias de validación para el extremo llamado.
item o items	La carga útil del extremo, ya sea un solo elemento o una colección de elementos.

Ejemplo JSON

{
  "message": "",
  "status": 200,
  "validations": [],
  "items": []
}

Validaciones

Cuando se detectan errores, se añade un objeto de validación a la matriz de validaciones del sobre de respuesta. El objeto de validación tiene las siguientes propiedades:

Nombre de la propiedad	Descripción
message	El mensaje de validación.
severidad	La gravedad de la validación: error advertencia información
campo	El campo al que hace referencia la validación.

Ejemplo JSON

{
  "message": "",
  "status": 400,
  "validations": [
    {
      "message": "CustomerId is mandatory.",
      "severity": "error",
      "field": "customerId"
    },
    {
      "message": "CompanyName is mandatory.",
      "severity": "error",
      "field": "companyName"
    }
  ],
}

Operaciones principales

Estas son las operaciones básicas que su servicio REST debería soportar. Algunos servicios, por supuesto, optarán por no desplegar ciertos métodos (por ejemplo, un servicio de solo lectura solo desplegaría métodos Obtener uno o Obtener muchos).

Conseguir soltero

La operación Obtener único devuelve un único registro. El identificador del registro se especifica en la URL.

Método HTTP

CONSEGUIR

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Ejemplo JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Consigue muchos

La operación Obtener Muchos devuelve muchos registros para una colección. A menudo, esta operación se utiliza junto con la paginación para permitir la lectura de una colección de registros.

Si es posible, se debe devolver un recuento de los registros de la colección. Esto permite que App Builder muestre el recuento de registros en la interfaz de usuario, además de informarle cuando se alcanza el final de la colección.

Método HTTP

CONSEGUIR

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers

Ejemplo JSON

{
  "count": 2,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Crear

La operación "Crear" creará un nuevo registro. El identificador del registro se encuentra dentro del cuerpo JSON.

Tenga en cuenta que el registro completo se refleja en la respuesta. Esto es útil cuando el servidor crea o actualiza algunos campos (como la marca de tiempo de creación de un registro).

Método HTTP

CORREO

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers

Ejemplo de cuerpo de solicitud JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Ejemplo de cuerpo de respuesta JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Actualizar

La operación de actualización actualiza un registro existente. El identificador del registro se especifica en la URL.

Tenga en cuenta que el registro completo se refleja en la respuesta. Esto es útil cuando el servidor crea o actualiza algunos campos (como la marca de tiempo de actualización de un registro).

Método HTTP

• PUT - Se utiliza para una actualización completa. Se deben especificar todos los parámetros del registro.
• POST - Se utiliza para una actualización parcial. Solo se deben especificar los parámetros obligatorios del registro.

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Ejemplo de cuerpo de solicitud JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Ejemplo de cuerpo de respuesta JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Borrar

La operación de eliminación elimina un registro. El identificador del registro se especifica en la URL. No es necesario enviar el cuerpo de la solicitud para una operación DELETE.

Método HTTP

BORRAR

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Ejemplo de cuerpo de respuesta JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Parámetros de consulta

Consigue muchos

En el nivel de recopilación, su extremo REST debe admitir las siguientes características.

Paginación

Para colecciones con muchos registros, suele ser necesario admitir la paginación. Para ello, App Builder define los siguientes parámetros:

Parámetro de consulta	Descripción	Ejemplo
$limit	El número máximo de registros a recuperar en una solicitud.	$limit=10
$offset	Desde qué desplazamiento de registro debe comenzar la búsqueda. Los desplazamientos se basan en cero, por lo que especificar 0 recuperará el primer registro de la colección.	$offset=10
$count	Un valor booleano que indica si se debe devolver un recuento de colecciones. En App Builder, este parámetro se considera falso por defecto.	$count=true

Ordenando

App Builder puede admitir una clasificación sencilla de campos.

Parámetro de consulta	Descripción	Ejemplo
$sort	Una lista de nombres de campos, delimitada por comas, para ordenar. Añada un guion (-) al nombre del campo para ordenarlo en orden descendente. En el ejemplo, ordene la colección por país (de menor a mayor) y por nombre de empresa (de mayor a menor).	$sort=-country,companyName

Filtrado

App Builder admite una cadena de filtro de consultar. Esta cadena admite un subconjunto de la especificación de filtro de cadena de consultar de OData 4.0. Para las comparaciones de cadenas, se pueden especificar comodines utilizando el % Carácter.

Parámetro de consulta	Descripción	Ejemplo
$filter	Una cadena de consultar de estilo OData 4.0 que filtra datos	$filter=country eq 'united%'

Operadores

Comparación

Operador	Descripción	Ejemplo
eq	Igual al valor.	categoryId eq 42
neq	No es igual al valor.	categoryId neq 42
gt	Mayor que el valor.	price gt 100
lt	Menor que el valor.	price lt 100
ge	Mayor o igual que el valor.	price ge 100
le	Menor o igual que el valor.	price le 100
in	Coincide con cualquier valor de la lista.	categoryId in (1, 2, 3)

Lógico

Operador	Descripción	Ejemplo
y	Y lógico	price gt 100 and categoryId in (1,2,3)

Limitaciones

• Sin operadores aritméticos
• No hay operadores lógicos o/no
• Sin operadores de agrupación
• Sin funciones de consultar
• Sin alias de parámetros

Buscar

App Builder ofrece un mecanismo para buscar registros en una colección. Esta búsqueda se realiza en todos los campos de búsqueda del registro.

App Builder agrega comodines al principio y al final de la cadena de búsqueda de forma predeterminada.

Parámetro de consulta	Descripción	Ejemplo
$q	Una cadena de búsqueda que se aplicará a todas las columnas de búsqueda de un registro.	$q=hello

Convenciones de tipos

Tipos JSON

Como regla general, los desarrolladores deberían preferir usar los tipos JSON nativos integrados. App Builder asigna automáticamente los tipos JSON nativos, por lo que se recomienda el uso directo de valores numéricos, booleanos, cadenas y nulos.

Fechas

App Builder codifica las fechas con el formato ISO 8601. Todas las fechas se serializan en UTC.

• https://en.wikipedia.org/wiki/ISO_8601

Control de versiones

Para gestionar futuras incompatibilidades entre las versiones de la API REST, App Builder incluye un número de versión directamente en la URL REST.

URL de ejemplo {: #example-url }> https://example.com/rest/v1/...

Operaciones opcionales

Otras operaciones que pueden ser útiles para incluir en una API CRUD REST.

Nuevo

La nueva operación se utiliza para devolver los valores predeterminados de los registros. Esto se utiliza antes de crear un registro en casos en los que el servidor REST puede rellenar previamente algunos datos.

Método HTTP

• OBTENER
• PUBLICAR.

URL de ejemplo {: #example-url }> https://example.com/rest/v1/sales/customers(new)

Ejemplo de cuerpo de respuesta JSON

{
  "item": {
    "customerId": null,
    "daysActive": 0
  }
  // envelope properties
}

JSON - Conversión de tablas relacionales

App Builder proporciona un mecanismo para convertir entre la representación de la tabla relacional interna de datos y el JSON esperado por los extremos REST.

Matrices a tablas

Cada matriz en una estructura JSON se considera una tabla relacional separada dentro de App Builder.

Como tal, la siguiente conversión se aplicaría a un extremo llamado "customers(get)":

Clientes(obtener) JSON

{
  "count": 2,
  "message": "Sample message",
  "status": 200,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Estructura de la tabla resultante

"clientes(obtener)"

Conteo	Mensaje	Estado
2	Mensaje de muestra	200

"clientes(obtener)/artículos"

ID del cliente	nombre	dirección
9775de33-08fc-4cd2-98ef-d91f3d5355b1	Sally Keith	Carretera Neutrino 4500
b603b276-a9bf-4328-88ff-8994176c38d1	John Henry	Unidad de Plutonio 130

Escritura de datos

Actualmente, App Builder solo permite escribir en una sola tabla durante un evento. Dado que cada array JSON se considera una tabla independiente, es posible que no se pueda escribir un objeto completo que contenga varios arrays en un solo evento de App Builder.

Como resultado, intente minimizar el uso de matrices JSON cuando sea posible, o admita la escritura de matrices en un objeto en un extremo de API REST separado.

Por ejemplo, un objeto "cliente" puede contener varias direcciones. Tener un extremo para escribir el objeto cliente y extremo para escribir las direcciones permite que App Builder se integre más fácilmente con la API REST.