Pregunta 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 API nueva, así que puedo tomar cualquier dirección en este momento. Mi tipo de contenido es XML en este momento, pero planeo apoyar a JSON en el futuro.

Ahora agrego 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 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 XML específica (es decir, ¡paguen más y obtendrá el almacenamiento que necesita!) Pero me detuve a pensarlo y me parece jabonoso (/ encogerse de hombros horrorizado). Además, parece que estoy dividiendo las respuestas de error en distintos casos, ya que algunos están impulsados ​​por código de estado http y otros están impulsados ​​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 hace la vida más fácil para el código del cliente?


545
2018-06-03 03:39


origen


Respuestas:


Así que al principio tuve la tentación de devolver el error de mi aplicación con 200 OK y una carga XML específica (es decir, ¡paguen más y obtendrá el almacenamiento que necesita!) Pero me detuve a pensarlo y me parece jabonoso (/ encogerse de hombros horrorizado).

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

Si se ha excedido la cuota de almacenamiento del cliente (por el motivo que sea), 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 no se ha cumplido la solicitud, DEBERÍA describir el motivo de la negativa en la entidad. Si el servidor no desea poner esta información a disposición del cliente, se puede usar el código de estado 404 (No encontrado).

Esto le dice al cliente que la solicitud fue correcta, pero que falló (algo que 200 no hace). 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ía en mente?


196
2018-06-03 04:08



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:

enter image description here

2XX / 3XX:

enter image description here

4XX:

enter image description here

5XX:

enter image description here


446
2017-12-16 23:34



La principal opción 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 (retorno 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 API mucho más notorias que no son REST que se llaman "RESTful".

En este punto (Agosto de 2015) 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 cuando se utilizan marcos de lo que era en el pasado. En particular, ahora es más fácil ver el caso de devolución no 200 y el cuerpo de respuestas que no son 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 descanso, xml o texto sin formato como la 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. Usualmente capaz, no siempre directo.

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

    envelope_ver: 1.0
    estado: # usa cualquier código que te guste. 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 buscar 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 poder cambiar la semántica de la API si es necesario.

  2. Documento...


80
2018-06-03 04:13



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


40
2018-06-03 05:46



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, también conocido como el cliente no puede cambiar nada a su solicitud para que la solicitud pase. Si se excede la cuota del cliente, definitivamente no es un error del servidor, por lo que se debe evitar 5xx.


22
2018-06-04 13:54



Sé que esto es muy 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 HTTP API", application / problem + json (https://tools.ietf.org/html/draft-nottingham-http-problem-05)


19
2017-12-18 09:49



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

5xxError 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 sus errores de aplicación depende realmente de usted. Stack Overflow, por ejemplo, envía un objeto con response, data y message propiedades. La respuesta que creo 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 el response es false)


17
2018-06-03 09:21



Convenido. La filosofía básica de REST es usar 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 útil HTTP. Ya son códigos universales establecidos que transmiten el estado de respuesta y, por lo tanto, para ser verdaderamente RESTful, 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, probablemente de una manera no estándar o patentada. Esto tampoco es eficiente: obligará a sus clientes a analizar la carga HTTP por vez única para comprender el estado de respuesta "real". Esto aumenta el procesamiento, agrega latencia y crea un ambiente para que el cliente cometa errores.


9
2017-11-21 17:38



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


6
2017-10-23 05:39