example - json rest api

¿Cómo exponer una API de validación de forma RESTful?

Question

En general soy un fanático del diseño RESTful API, pero no estoy seguro de cómo aplicar los principios REST para una API de validación.

Supongamos que tenemos una API para consultar y actualizar la información de perfil de un usuario (nombre, correo electrónico, nombre de usuario, contraseña). Hemos considerado que una pieza útil de la funcionalidad para exponer sería la validación, por ejemplo, consultar si un nombre de usuario dado es válido y está disponible.

¿Cuáles son los recursos en este caso? ¿Qué códigos de estado HTTP y / o encabezados deberían usarse?

Para empezar, tengo GET /profile/validate que toma los parámetros de cadena de consulta y devuelve 204 o 400 si es válido o inválido. Pero validate es claramente un verbo y no un sustantivo.

Answer 1

El tipo de cosa que describiste es ciertamente más estilo RPC en su semántica, pero eso no significa que no puedas alcanzar tus metas de manera RESTANTE.

No hay un verbo HTTP VALIDADO, entonces, ¿cuánto valor puede obtener al estructurar una API completa alrededor de eso? Su historia se centra en proporcionarles a los usuarios la capacidad de determinar si un nombre de usuario dado está disponible; eso me suena como una simple verificación de recuperación de recursos: GET: /profile/username/... - si el resultado es un 404, el nombre está disponible.

Lo que resalta es que esa validación del lado del cliente es solo eso: del lado del cliente. Es una preocupación de UI garantizar que los datos se validan en el cliente antes de enviarlos al servidor. Un servicio RESTful no da ni un ápice, haya o no haya realizado un cliente la validación; simplemente aceptará o rechazará una solicitud basada en su propia lógica de validación.

REST no es un paradigma que lo abarque todo, solo describe una forma de estructurar las comunicaciones entre el cliente y el servidor.

Answer 2

Es mejor tener la validación en la API REST. Necesita una validación de todos modos y no lo use en el lado del cliente. En mi caso, tengo una convención en la API de que un error_id especial representa errores de validación y en el error_details hay una matriz de mensajes de error para cada campo que tiene errores en esta llamada PUT o POST. Para el examen:

{
  "error": true,
  "error_id": 20301,
  "error_message": "Validation failed!",
  "error_details": {
    "number": [
      "Number must not be empty"
    ],
    "ean": [
      "Ean must not be empty",
      "Ean is not a valid EAN"
    ]
  }
}

Si utiliza la misma API REST para aplicaciones web y móviles, le gustará la posibilidad de cambiar la validación en ambas solo actualizando la API. Especialmente las actualizaciones móviles tardarían más de 24 horas en publicarse en las tiendas.

Y así es como se ve en la aplicación móvil:

La respuesta del PUT o POST se usa para mostrar los mensajes de error para cada campo. Esta es la misma llamada de una aplicación web que usa React:

De esta forma, todos los códigos de respuesta de la API REST, como 200, 404, tienen el significado que deberían. Una llamada PUT responde con 200 incluso si la validación falla. Si la llamada pasa la validación, la respuesta sería así:

{
  "error": false,
  "item": {
"id": 1,
"created_at": "2016-08-03 13:58:11",
"updated_at": "2016-11-30 08:55:58",
"deleted_at": null,
"name": "Artikel 1",
"number": "1273673813",
"ean": "12345678912222"
  }
}

Hay posibles modificaciones que podrías hacer. Maby lo usa sin un error_id. Si hay un error_details simplemente bucleelos y si encuentra una clave que tiene el mismo nombre que un campo, coloque su valor como texto de error en el mismo campo.

Answer 3

Está confundiendo REST con la orientación de recursos, no hay nada en REST que diga que no puede usar verbos en las URL. Cuando se trata del diseño de URL, generalmente elijo lo que sea más autodescriptivo, wheather es sustantivo o verbo.

Acerca de su servicio, lo que yo haría es usar el mismo recurso que usa para actualizar, pero con un parámetro de cadena de test , de modo que cuando test=1 la operación no está completa, pero puede usarla para devolver los errores de validación.

PATCH /profile?test=1
Content-Type: application/x-www-form-urlencoded

dob=foo

... y la respuesta:

HTTP/1.1 400 Bad Request
Content-Type: text/html

<ul class="errors">
  <li data-name="dob">foo is not a valid date.</li>
</ul>

Answer 4

También hemos encontrado el mismo problema. Nuestro razonamiento para hacer que el cliente se retrase al servidor para la validación fue para evitar que las reglas no coincidan. El servidor debe validar todo antes de actuar sobre los recursos. No tiene sentido codificar estas reglas dos veces y tienen este potencial para que no se sincronicen. Por lo tanto, hemos ideado una estrategia que parece seguir con la idea de REST y al mismo tiempo nos permite pedirle al servidor que realice la validación.

Nuestro primer paso fue implementar un objeto de metadatos que se puede solicitar desde un servicio de metadatos ( GET /metadata/user ). Este objeto de metadatos se usa para decirle al cliente cómo hacer validaciones básicas del lado del cliente (requerimiento, tipo, longitud, etc.). Generamos la mayoría de estos desde nuestra base de datos.

La segunda parte consiste en agregar un nuevo recurso llamado análisis. Entonces, por ejemplo, si tenemos un servicio:

GET /users/100

Crearemos un nuevo recurso llamado:

POST /users/100/analysis

El recurso de análisis contiene no solo los errores de validación que se produjeron, sino también información estadística que podría ser relevante si fuera necesario. Uno de los temas que hemos debatido fue qué verbo utilizar para el recurso de análisis. Hemos concluido que debe ser un POST ya que el análisis se está creando en el momento de la solicitud. Sin embargo, también ha habido fuertes argumentos para GET.

Espero que esto sea útil para otros que intentan resolver este mismo problema. Cualquier comentario sobre este diseño es apreciado.