principios practicas patterns mejores estandares ejemplo diseño web-services http rest

web services - practicas - Error de API REST devoluciones buenas prácticas



rest api mejores practicas (12)

Así que al principio tuve la tentación de devolver el error de mi aplicación con 200 OK y una carga útil XML específica (es decir. ¡Páganos más y obtendrás el almacenamiento que necesitas!) Pero me detuve a pensar en ello y parece que se empapaba (/ encogiéndose de hombros con horror).

No devolvería un 200 a menos que realmente no hubiera nada malo con la solicitud. De RFC2616 , 200 significa "la solicitud se ha realizado correctamente".

Si se ha excedido la cuota de almacenamiento del cliente (por cualquier motivo), devolvería un 403 (Prohibido):

El servidor entendió la solicitud, pero se niega a cumplirla. La autorización no ayudará y la solicitud NO DEBE repetirse. Si el método de solicitud no era HEAD y el servidor desea hacer público el motivo por el cual la solicitud no se ha cumplido, DEBE describir el motivo de la denegación en la entidad. Si el servidor no desea que esta información esté disponible para el cliente, se puede usar el código de estado 404 (No encontrado) en su lugar.

Esto le dice al cliente que la solicitud estaba bien, pero que falló (algo que no hace un 200). Esto también le da la oportunidad de explicar el problema (y su solución) en el cuerpo de respuesta.

¿Qué otras condiciones de error específicas tenías en mente?

Estoy buscando orientación sobre buenas prácticas cuando se trata de devolver errores de una API REST. Estoy trabajando en una nueva API, así que puedo tomar cualquier dirección ahora mismo. Mi tipo de contenido es XML en este momento, pero planeo admitir JSON en el futuro.

Ahora estoy agregando algunos casos de error, como por ejemplo, un cliente intenta agregar un nuevo recurso pero ha excedido su cuota de almacenamiento. Ya estoy manejando ciertos casos de error con los códigos de estado HTTP (401 para autenticación, 403 para autorización y 404 para URI de solicitud errónea). Revisé los códigos de error HTTP bendecidos, pero ninguno del rango 400-417 parece correcto para informar errores específicos de la aplicación. Así que al principio tuve la tentación de devolver el error de mi aplicación con 200 OK y una carga útil XML específica (es decir. ¡Páganos más y obtendrás el almacenamiento que necesitas!) Pero me detuve a pensar en ello y parece que se empapaba (/ encogiéndose de hombros con horror). Además, parece que estoy dividiendo las respuestas de error en distintos casos, ya que algunos están basados ​​en el código de estado http y otros en el contenido.

Entonces, ¿cuáles son las recomendaciones de la industria? Buenas prácticas (¡explique por qué!) Y también, desde un punto de vista del cliente, ¿qué tipo de manejo de errores en la API REST hace la vida más fácil para el código del cliente?

Como han señalado otros, tener una entidad de respuesta en un código de error es perfectamente permisible.

Recuerde que los errores 5xx son del lado del servidor, alias el cliente no puede cambiar nada a su solicitud para hacer que la solicitud sea aprobada. Si se excede la cuota del cliente, eso definitivamente no es un error del servidor, por lo que se debe evitar 5xx.

Convenido. La filosofía básica de REST es utilizar la infraestructura web. Los códigos de estado de HTTP son el marco de mensajería que permite a las partes comunicarse entre sí sin aumentar la carga útil de HTTP. Ya están establecidos códigos universales que transmiten el estado de respuesta y, por lo tanto, para ser verdaderamente RESTOS, las aplicaciones deben usar este marco para comunicar el estado de respuesta.

El envío de una respuesta de error en un sobre HTTP 200 es engañoso y obliga al cliente (consumidor de API) a analizar el mensaje, muy probablemente de una manera no estándar o de propiedad. Esto tampoco es eficiente: obligará a sus clientes a analizar la carga HTTP cada vez que entiendan el estado de respuesta "real". Esto aumenta el procesamiento, agrega latencia y crea un entorno para que el cliente cometa errores.

Hay dos tipos de errores. Errores de aplicación y errores de HTTP. Los errores de HTTP son solo para hacerle saber a su manejador AJAX que las cosas fueron bien y no deberían usarse para nada más.

Error del servidor 5xx

500 Internal Server Error 501 Not Implemented 502 Bad Gateway 503 Service Unavailable 504 Gateway Timeout 505 HTTP Version Not Supported 506 Variant Also Negotiates (RFC 2295 ) 507 Insufficient Storage (WebDAV) (RFC 4918 ) 509 Bandwidth Limit Exceeded (Apache bw/limited extension) 510 Not Extended (RFC 2774 )

2xx exito

200 OK 201 Created 202 Accepted 203 Non-Authoritative Information (since HTTP/1.1) 204 No Content 205 Reset Content 206 Partial Content 207 Multi-Status (WebDAV)

Sin embargo, la forma en que diseñe los errores de su aplicación depende realmente de usted. Desbordamiento de pila, por ejemplo, envía un objeto con response , data y propiedades de message . Creo que la respuesta contiene true o false para indicar si la operación fue exitosa (generalmente para operaciones de escritura). Los datos contienen la carga útil (generalmente para operaciones de lectura) y el mensaje contiene metadatos adicionales o mensajes útiles (como mensajes de error cuando la response es false ).

La opción principal es si desea tratar el código de estado HTTP como parte de su API REST o no.

Ambas formas funcionan bien. Estoy de acuerdo en que, estrictamente hablando, una de las ideas de REST es que debe usar el código de estado HTTP como parte de su API (devuelva 200 o 201 para una operación exitosa y un 4xx o 5xx dependiendo de varios casos de error). Sin embargo , no hay policía REST. Puedes hacer lo que quieras. He visto muchas API no REST más notorias que se llaman "RESTful".

En este momento (agosto de 2015), le recomiendo que utilice el código de estado HTTP como parte de su API. Ahora es mucho más fácil ver el código de retorno cuando se usan marcos que en el pasado. En particular, ahora es más fácil ver el caso de devolución no-200 y el cuerpo de respuestas no-200 que en el pasado.

El código de estado HTTP es parte de su api

  1. Deberá elegir cuidadosamente los códigos 4xx que se ajusten a sus condiciones de error. Puede incluir un resto, un xml o un mensaje de texto sin formato como carga útil que incluye un subcódigo y un comentario descriptivo.

  2. Los clientes deberán usar un marco de software que les permita obtener el código de estado de nivel HTTP. Por lo general se puede hacer, no siempre es sencillo.

  3. Los clientes deberán distinguir entre los códigos de estado HTTP que indican un error de comunicación y sus propios códigos de estado que indican un problema de nivel de aplicación.

El código de estado HTTP no es parte de su api

  1. El código de estado HTTP siempre será 200 si su aplicación recibió la solicitud y luego respondió (casos de error y éxito)

  2. TODAS sus respuestas deben incluir información de "sobre" o "encabezado". Típicamente algo como:

    envelope_ver: 1.0 status: # use any codes you like. Reserve a code for success. msg: "ok" # A human string that reflects the code. Useful for debugging. data: ... # The data of the response, if any.

  3. Este método puede ser más fácil para los clientes, ya que el estado de la respuesta siempre está en el mismo lugar (no se necesitan subcódigos), no hay límites en los códigos, no es necesario obtener el código de estado de nivel HTTP.

Aquí hay una publicación con una idea similar: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Temas principales:

  1. Asegúrese de incluir los números de versión para que luego pueda cambiar la semántica de la API si es necesario.

  2. Documento...

No olvide los errores 5xx también para errores de aplicación.

En este caso, ¿qué hay de 409 (Conflicto)? Esto supone que el usuario puede solucionar el problema eliminando los recursos almacenados.

De lo contrario, 507 (no completamente estándar) también puede funcionar. No usaría 200 a menos que usen 200 para errores en general.

Por favor, apégate a la semántica del protocolo. Utilice 2xx para las respuestas exitosas y 4xx, 5xx para las respuestas de error, ya sean sus excepciones comerciales u otras. Si el uso de 2xx para cualquier respuesta hubiera sido el caso de uso previsto en el protocolo, en primer lugar no tendrían otros códigos de estado.

Si se excede la cuota del cliente es un error del servidor, evite 5xx en esta instancia.