Recomendaciones de la API REST en Jitterbit App Builder

Descripción general

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

Para los propósitos de este documento, asumiremos que el desarrollador se centra 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.).

Principios de diseño RESTful

En la medida de lo posible, la API REST de App Builder sigue estos principios RESTful:

• Los servicios son sin estado.
• Los endpoints 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 son inseguras, pero 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. Debido a esto, las operaciones POST pueden contener datos parciales.
• Los códigos de estado HTTP indican si ocurrió un error.
• Se utilizan tipos de medios para realizar la negociación de contenido. Sin embargo, en este momento, App Builder solo admite JSON (application/json) y UTF-8.

App Builder no se adhiere a todos los principios RESTful:

• Los cuerpos de solicitud y respuesta de recursos están envueltos 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 están envueltos en un sobre. Los sobres permiten que los datos se envíen hacia y desde un endpoint de API fuera de la carga útil del endpoint.

Cuerpo de la solicitud sobre

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

Ejemplo de JSON

{
  "item": {}
}

Cuerpo de la respuesta envelope

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

Ejemplo de JSON

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

Validaciones

Cuando se encuentran errores, se agrega un objeto de validación al arreglo de validaciones en el envelope 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 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 generará un nuevo registro. El identificador para el registro se encuentra dentro del cuerpo JSON.

Nota 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

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 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 actualización del registro).

Método HTTP

• PUT - Usado para una actualización completa. Todos los parámetros del registro deben ser especificados.
• POST - Usado 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á 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ógico

Limitaciones

• Sin operadores aritméticos
• Sin operadores lógicos or/not
• Sin operadores de agrupamiento
• Sin funciones de consulta
• Sin 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://es.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.

Ejemplo de URL

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
}

JSON - Conversión de tablas relacionales

App Builder proporciona un mecanismo para convertir entre la representación interna de tablas relacionales de datos y 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.

Como tal, 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 debe 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.