Recomendaciones de la API REST en Jitterbit App Builder

Introducción

Esta página ofrece orientación para desarrolladores que buscan implementar una API REST compatible con App Builder. Se asume que el desarrollador está enfocado en crear un servicio REST CRUD. 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.).

Sobre envoltura

Los cuerpos de solicitud y respuesta de la API REST de App Builder están envueltos en una envoltura. Las envolturas permiten que los datos se envíen hacia y desde un punto final de API fuera de la carga útil del punto final.

Envoltura del cuerpo de solicitud

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

Ejemplo JSON

{
  "item": {}
}

Envoltura del cuerpo de respuesta

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

Example JSON

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

Validations

Cuando se encuentran errores, se agrega un objeto de validación al array de validaciones en el sobre de respuesta. El objeto de validación tiene las siguientes propiedades:

Example JSON

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

Core operations

Estas son las operaciones básicas que tu servicio REST debería soportar. Algunos servicios, por supuesto, elegirán no implementar ciertos métodos (por ejemplo, un servicio de solo lectura solo implementaría los métodos Obtener Único/Obtener Muchos).

Get single

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

HTTP method

GET

Example URL

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Example JSON

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

Get many

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 que se revise una colección de registros.

Si es posible, se debe devolver un conteo de los registros en la colección. Esto permite que App Builder muestre el conteo de registros en la interfaz de usuario, así como informar a la interfaz de usuario cuando se ha alcanzado el final de la colección.

Método HTTP

GET

URL de ejemplo

https://example.com/rest/v1/sales/customers

JSON de ejemplo

{
  "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 para el registro existe dentro del cuerpo JSON.

Nota que todo el registro se devuelve en la respuesta. Esto es útil en casos donde algunos campos son creados o actualizados por el servidor (como una marca de tiempo de creación del registro).

Método HTTP

POST

URL de ejemplo

https://example.com/rest/v1/sales/customers

Cuerpo de solicitud JSON de ejemplo

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

Cuerpo de respuesta JSON de ejemplo

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

Actualizar

La operación Actualizar actualizará un registro existente. El identificador para el registro se especifica en la URL.

Nota que todo el registro se devuelve en la respuesta. Esto es útil en casos donde algunos campos son creados o actualizados por el servidor (como una marca de tiempo de actualización del registro).

Método HTTP

• PUT: Se utiliza para una actualización completa. Todos los parámetros del registro deben ser especificados.

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

URL de ejemplo

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Cuerpo de solicitud JSON de ejemplo

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

Cuerpo de respuesta JSON de ejemplo

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

Eliminar

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

Método HTTP

DELETE

URL de ejemplo

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Cuerpo de respuesta JSON de ejemplo

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

Parámetros de consulta

Obtener muchos

A nivel de colección, su punto final REST debe admitir las siguientes características.

Paginación

Para colecciones que contienen muchos registros, a menudo es necesario admitir la paginación. Para admitir la paginación, App Builder define los siguientes parámetros:

Ordenamiento

App Builder puede admitir un ordenamiento simple de campos.

Filtrado

App Builder proporciona soporte para una cadena de filtro de consulta. La cadena de filtro de consulta admite un subconjunto de la especificación de filtro de cadena de consulta OData 4.0. Para comparaciones de cadenas, se pueden especificar comodines utilizando el carácter %.

Operadores

Comparación

Lógicos

Limitaciones

• No hay operadores aritméticos.

• No hay operadores lógicos or/not.

• No hay operadores de agrupamiento.

• No hay funciones de consulta.

• No hay alias de parámetros.

Búsqueda

App Builder proporciona un mecanismo para buscar registros en una colección. Esta búsqueda opera en todos los campos buscables del registro.

El App Builder, por defecto, añade comodines al principio y al final de la cadena de búsqueda.

Convenciones de tipo

Tipos JSON

Como regla general, los desarrolladores deben preferir el uso de los tipos JSON nativos incorporados. El App Builder asigna automáticamente los tipos JSON nativos, por lo que se recomienda el uso directo de numéricos, booleanos, cadenas y nulos.

Fechas

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

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

Versionado

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

URL de ejemplo

https://example.com/rest/v1/...

Operaciones opcionales

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

Nuevo

La operación nueva se utiliza para devolver los valores predeterminados del registro. Esto se utiliza antes de crear un registro en casos donde algunos datos pueden estar prellenados por el servidor REST.

Método HTTP

• GET

• POST

URL de ejemplo

https://example.com/rest/v1/sales/customers(new)

Cuerpo de respuesta JSON de ejemplo

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

Conversión de JSON - Tablas relacionales

El App Builder proporciona un mecanismo para convertir entre la representación interna de tablas relacionales de datos y JSON esperado por los puntos finales REST.

Arreglos a tablas

Cada arreglo en una estructura JSON se considera una tabla relacional separada dentro del App Builder.

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

customers(get) 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 tabla resultante

customers(get)

customers(get)/items

Escribiendo datos

Actualmente, App Builder solo admite la escritura en una sola tabla durante un evento. Dado que cada arreglo JSON se considera una tabla separada, escribir un objeto completo que comprenda múltiples arreglos en un solo evento de App Builder puede no ser compatible.

Como resultado, se debe minimizar el uso de arreglos JSON siempre que sea posible, o admitir la escritura de los arreglos en un objeto en un punto final REST API separado.

Por ejemplo, un objeto "cliente" puede contener múltiples direcciones. Tener un punto final para escribir el objeto cliente y otro punto final para escribir las direcciones permite que App Builder se integre más fácilmente con su REST API.