REST API error devuelve buenas prácticas [cerrado]

Estoy buscando orientación sobre buenas prácticas cuando se trata de devolver errores de una API REST. Estoy trabajando en una nueva API para poder tomar cualquier dirección en este momento. 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 códigos de estado HTTP (401 para autenticación, 403 para autorización y 404 para URI de solicitud incorrecta). Revisé los benditos códigos de error HTTP, 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á el almacenamiento que necesita!), Pero me detuve a pensarlo y parece estar enjabonado (/ encogerse de hombros con horror). Además, parece que estoy dividiendo las respuestas de error en casos distintos, ya que algunos están controlados por el código de estado http y otros están controlados por 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 facilita la vida del código del cliente?

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á el almacenamiento que necesita!), Pero me detuve a pensarlo y parece estar enjabonado (/ encogerse de hombros con horror).

No devolvería un 200 a menos que realmente no haya nada malo con la solicitud. De RFC2616 , 200 significa "la solicitud ha tenido éxito".

Si se ha excedido la cuota de almacenamiento del cliente (por cualquier razón), 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 por qué la solicitud no se ha cumplido, DEBERÍA 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 utilizar el código de estado 404 (No encontrado).

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

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

Un gran recurso para elegir el código de error HTTP correcto para su API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Un extracto del artículo:

Donde empezar:

2XX / 3XX:

4XX:

5XX:

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). , no hay policía REST. Puedes hacer lo que quieras. He visto APIs no REST mucho más atroces que se llaman "RESTful".

En este punto (agosto de 2015), le recomiendo que use el código de estado HTTP como parte de su API. Ahora es mucho más fácil ver el código de retorno al usar frameworks 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 mensaje de reposo, xml o texto sin formato como la carga útil que incluye un subcódigo y un comentario descriptivo.

2. Los clientes deberán utilizar un marco de software que les permita obtener el código de estado de nivel HTTP. Generalmente factible, no siempre sencillo.

3. Los clientes tendrán que 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 a 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 éxito y error)

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

   sobre_ver: 1.0
   estado: # usa los códigos que quieras. Reserve un código para el éxito.
   msg: "ok" # Una cadena humana que refleja el código. Útil para la depuración.
   data: ... # Los datos de la respuesta, si los hay.

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 números de versión para que luego pueda cambiar la semántica de la API si es necesario.

2. Documento...

Recuerde que hay más códigos de estado que los definidos en los RFC HTTP / 1.1, el registro de la IANA se encuentra en http://www.iana.org/assignments/http-status-codes . Para el caso que mencionó, el código de estado 507 suena bien.

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

Recuerde que los errores 5xx son del lado del servidor, es decir, el cliente no puede cambiar nada a su solicitud para que la solicitud sea aprobada. Si se supera la cuota del cliente, definitivamente no se trata de un error del servidor, por lo que debe evitarse 5xx.

Hay dos tipos de errores. Errores de aplicación y errores HTTP. Los errores HTTP son solo para informarle a su controlador AJAX que las cosas salieron bien y no deberían usarse para otra cosa.

5xx Error del Servidor

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 éxito

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, datay messagepropiedades. La respuesta que creo contiene trueo falsepara 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 responsees false).

Sé que esto es extremadamente tarde para la fiesta, pero ahora, en el año 2013, tenemos algunos tipos de medios para cubrir el manejo de errores de una manera distribuida común (RESTful). Consulte "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) y "Detalles del problema para las API HTTP", application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

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

Enviar 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 manera no estándar o propietaria. Esto tampoco es eficiente: obligará a sus clientes a analizar la carga HTTP cada vez para comprender el estado de respuesta "real". Esto aumenta el procesamiento, agrega latencia y crea un entorno para que el cliente cometa errores.

Modelar su API en las 'mejores prácticas' existentes podría ser el camino a seguir. Por ejemplo, así es como Twitter maneja los códigos de error https://developer.twitter.com/en/docs/basics/response-codes

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

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

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

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

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