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.

Cuerpo de solicitud de envoltura

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

Ejemplo JSON

{
  "item": {}
}

Cuerpo de respuesta de envoltura

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

Ejemplo JSON

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

Validaciones

Cuando se encuentran errores, se agrega un objeto de validación al arreglo de validaciones en la envoltura de respuesta. El objeto de validación tiene las siguientes propiedades:

Ejemplo de JSON

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

Operaciones básicas

Estas son las operaciones básicas que su 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).

Obtener único

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

Método HTTP

GET

Ejemplo de URL

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

Ejemplo de JSON

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

Obtener 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 que se explore 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

Ejemplo de URL

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

Ejemplo de 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 existe dentro del cuerpo JSON.

Tenga en cuenta que el registro completo 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

Ejemplo de 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 Actualizar actualizará un registro existente. El identificador del 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.

Ejemplo de 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
}

Eliminar

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

Método HTTP

DELETE

Ejemplo de 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

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 soportar el 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ógico

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.

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. App Builder mapea automáticamente los tipos JSON nativos, por lo que se fomenta el uso directo de numéricos, booleanos, cadenas y nulos.

Fechas

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

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

Versionado

Para manejar incompatibilidades futuras entre versiones de la API REST, 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 ser prellenados por el servidor REST.

Método HTTP

• GET

• POST

Ejemplo de URL

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

Ejemplo de cuerpo de respuesta JSON

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

Conversión de JSON a tablas relacionales

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

Arreglos a tablas

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

Por lo tanto, la siguiente conversión se aplicaría a un endpoint 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

Escritura de 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 recomienda minimizar el uso de arreglos JSON cuando sea posible, o admitir la escritura de los arreglos en un objeto en un endpoint REST API separado.

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