Recomendaciones de API REST

Descripción General

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

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 se aplicarán a otras APIs. Sin embargo, es probable que una API CRUD tenga 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, 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:

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

Sobre

App Builder los cuerpos de las solicitudes y respuestas de la API REST se envuelven 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 App Builder el cuerpo de la solicitud de API REST contiene estas propiedades de sobre:

Ejemplo JSON

{
  "item": {}
}

Sobre del Cuerpo de Respuesta

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

Ejemplo JSON

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

Validaciones

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

Ejemplo 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, optarán por no desplegar determinados 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

Ejemplo de 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 de 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 App Builder para mostrar el recuento de registros en la interfaz de usuario, así como para informar a la interfaz de usuario cuando se ha llegado al final de la recopilación.

Método HTTP

CONSEGUIR

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

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

Método HTTP

CORREO

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 de actualización actualizará un registro existente. El identificador del registro se especifica en la URL.

Tenga en cuenta que todo el registro se refleja en la respuesta. Esto resulta útil en los casos en los que el servidor crea o actualiza algunos campos (como una 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.

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
}

Borrar

La operación de eliminación eliminará 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

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

Consigue Muchos

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

Paginación

Para las 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:

| Parámetro de consulta | Descripción | Ejemplo | | --- | --- | --- |TABLEROWEND| (limit_ | La cantidad máxima 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 si se especifica 0, se obtendrá el primer registro de la colección. | $offset=10| | $count | Un valor booleano que indica si se debe devolver un recuento de colecciones. App Builder, este parámetro se considera falso de forma predeterminada. | $count=true|

Ordenando

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

Filtrado

App Builder proporciona compatibilidad con una cadena de filtro de consultar. La cadena de filtro de consultar 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.

Operadores

Comparación

Lógico

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 proporciona un mecanismo para buscar registros en una colección. Esta búsqueda funciona en todos los campos de búsqueda del registro.

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

Convenciones de Tipo

Tipos JSON

Como regla general, los desarrolladores deberían preferir utilizar los tipos JSON nativos integrados. App Builder asigna automáticamente tipos JSON nativos, por lo que se recomienda el uso directo de valores numéricos, booleanos, cadenas y valores 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

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.

Ejemplo de 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 valores predeterminados de registros. Esto se utiliza antes de crear un registro en los casos en los que el servidor REST puede rellenar previamente algunos datos.

Método HTTP

• OBTENER
• PUBLICAR.

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 de datos de la tabla relacional interna y el JSON esperado por los extremos REST.

Matrices a Tablas

Cada matriz en una estructura JSON se considera una tabla relacional independiente 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) "

"clientes(obtener)/artículos"

Escritura de Datos

Actualmente, App Builder solo admite la escritura en una sola tabla durante un evento. Dado que cada matriz JSON se considera una tabla independiente, escribir un objeto completo que comprende varias matrices en una sola App Builder es posible que el evento no sea compatible.

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 otro extremo para escribir las direcciones permite App Builder para integrarse más fácilmente con su API REST.