Recomendaciones de API REST¶

Descripción General¶

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

A los efectos de este documento, asumiremos que el desarrollador se centra en crear 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 Vinyl (paginación, búsqueda, filtrado, etc.).

Principios de Diseño RESTful¶

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

• Los servicios son apátridas.
• 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. Debido a esto, las operaciones POST 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 contenidos. Por el momento, sin embargo, Vinyl sólo admite JSON (application/json) y UTF-8.

Vinyl no cumple con todos los principios RESTful:

• Los cuerpos de solicitud y respuesta de recursos se envuelven en un sobre. Esto permite que Vinyl incluya información adicional, como mensajes de eventos y resultados de validación.
• Las respuestas a los recursos no son hipermedia: no incluyen enlaces a otros recursos.

Sobre¶

Los cuerpos de solicitud y respuesta de Vinyl REST API están envueltos en un sobre. Los sobres permiten enviar datos hacia y desde un extremo API fuera de la carga útil del extremo.

Solicitar Sobre del Cuerpo¶

El cuerpo de solicitud de Vinyl REST API contiene estas propiedades de sobre:

Ejemplo JSON¶

{
  "item": {}
}

Sobre del Cuerpo de Respuesta¶

El cuerpo de respuesta de Vinyl REST API contiene estas propiedades de envolvente:

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 Principales¶

Estas son las operaciones básicas que debería admitir su servicio REST. Por supuesto, algunos servicios optarán por no desplegar ciertos métodos (por ejemplo, un servicio de solo lectura solo desplegaría métodos Get Single/Get Many).

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¶

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"
  }
}

Conseguir 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 a Vinyl mostrar el recuento de registros en la interfaz de usuario y también informar a la interfaz de usuario cuando se ha llegado al final de la colección.

Método HTTP¶

CONSEGUIR

URL de Ejemplo¶

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 todo el registro se repite en la respuesta. Esto es útil en los casos en los que el servidor crea o actualiza algunos campos (como una marca de tiempo de creación de registros).

Método HTTP¶

CORREO

URL de Ejemplo¶

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.

Tenga en cuenta que todo el registro se repite en la respuesta. Esto es útil en los casos en los que el servidor crea o actualiza algunos campos (como una marca de tiempo de actualización de registros).

Método HTTP¶

• PUT - Se utiliza para una actualización completa. Es necesario especificar todos los parámetros del registro.
• POST - Se utiliza para una actualización parcial. Sólo es necesario especificar los parámetros obligatorios del registro.

URL de Ejemplo¶

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 ningún cuerpo de solicitud para ELIMINAR.

Método HTTP¶

BORRAR

URL de Ejemplo¶

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¶

Conseguir Muchos¶

A nivel de colección, su extremo REST debe admitir las siguientes funciones.

Paginación¶

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

Clasificación¶

El vinilo puede admitir una clasificación sencilla de los campos.

Filtración¶

Vinyl proporciona soporte para 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 OData 4.0. Para comparaciones de cadenas, se pueden especificar comodines usando el % personaje.

Operadores¶

Comparación¶

Lógico¶

Limitaciones¶

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

Buscar¶

El vinilo proporciona un mecanismo para buscar registros en una colección. Esta búsqueda opera en todos los campos de búsqueda del registro.

Vinyl agrega de forma predeterminada 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 integrados nativos. Vinyl asigna automáticamente tipos JSON nativos, por lo que se recomienda el uso directo de números, valores booleanos, cadenas y valores nulos.

Fechas¶

El vinilo codifica fechas utilizando el formato ISO 8601. Todas las fechas están serializadas en UTC.

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

Versionado¶

Para gestionar futuras incompatibilidades entre versiones de API REST, Vinyl 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 CRUD REST.

Nuevo¶

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

Método HTTP¶

• CONSEGUIR
• CORREO.

URL de Ejemplo¶

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¶

Vinyl 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 Vinyl.

Como tal, la siguiente conversión se aplicaría a un extremo denominado "clientes(obtener)":

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"

Escribir Datos¶

Actualmente, Vinyl solo admite la escritura en una única mesa durante un evento. Dado que cada matriz JSON se considera una tabla separada, es posible que no se admita la escritura de un objeto completo que comprenda varias matrices en un solo evento de Vinyl.

Como resultado, busque minimizar el uso de matrices JSON siempre que sea posible, o admita la escritura de las matrices en un objeto en un extremo de API REST independiente.

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