12 Pregunta: Error de API REST devoluciones buenas prácticas [cerrado]

pregunta creada en Sat, Oct 7, 2017 12:00 AM

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 ahora mismo. Mi tipo de contenido es XML en este momento, pero planeo ser compatible con 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 la autenticación, 403 para la autorización y 404 para los URI de solicitud incorrecta). 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águenos más y obtendrá el almacenamiento que necesita!) 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 casos distintos, 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 el punto de vista de un cliente, ¿qué tipo de manejo de errores en la API REST hace la vida más fácil para el código del cliente?

    
599
  1. Solo para aclarar: no estoy muy interesado en qué código de estado HTTP particular devolver, pero si es una buena práctica REST para combinar errores de carga útil con códigos de estado HTTP o es mejor confiar únicamente en la carga útil.
    2009-06-03 18: 04: 55Z
  2. El manual de diseño de API REST cubre este tema bastante bien.
    2012-07-30 20: 31: 44Z
  3. La pregunta no pide opinión, sino orientación /recomendaciones, y debe volver a abrirse y usarse como referencia. ¿Cuál fue el punto para cerrar en 2016 la pregunta, que fue creada en 2009, tiene más de 400 votos y ninguna de las respuestas existentes se basa en opiniones
    2017-10-07 13: 41: 25Z
  4. La mayoría no mencionó, pero el uso de los códigos de error HTTP puede ocasionar problemas relacionados con la causa principal de un problema. HTTP es el protocolo de transporte y un 404 debe indicar que hubo un problema con el nivel de transporte de URLon (p. Ej., Ruta incorrecta). Si la aplicación no puede encontrar un conjunto de datos por su id, este es un error de nivel de la aplicación (no un error de nivel de transporte) y un 404, como lo sugieren los usuarios de código de estado de http, puede llevar a una conclusión errónea. En general, no me gusta la combinación de transporte y capa de aplicación al usar los códigos de estado.
    2018-02-14 12: 23: 50Z
12 Respuestas                              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 pensarlo y parece que jabonosa (/encogerse de hombros con horror).

No devolvería un 200 a menos que realmente no hubiera ningún problema 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 no se ha cumplido con la solicitud, 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 estuvo bien, pero que falló (sAlgo 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ías en mente?

    
214
2009-06-03 04: 08: 13Z
  1. Debo incluir mi mensaje de error detallado en el cuerpo, es decir. un código XML /par de cadenas? ¿Cómo están los clientes lidiando mejor con esto? Por ejemplo, sé que los clientes basados ​​en C # WebRequest lanzarán 'Solicitud incorrecta' o 'Prohibido' y no darán el cuerpo de respuesta.
    2009-06-03 04: 17: 06Z
  2. El cuerpo de un 403 "debería" contener los detalles del error. Si un cliente está preparado para hacer uso de la información es otra historia. Tiene más sentido que este formato sea el mismo que el de todas las demás cargas útiles (por ejemplo, XML, JSON).
    2009-06-03 04: 30: 01Z
  3. ... y si los detalles no se devuelven en el 403, se puede usar un 404 "can" (no me parece la mejor opción, aunque).
    2009-06-03 04: 33: 02Z
  4. La opción 404 es para el evento de que un 403 pueda revelar detalles sobre la aplicación que usted no quiere que conozcan los usuarios no autorizados, si un usuario no administrativo acierta por ejemplo, es posible que no desee que ese usuario sepa que es una URL válida para los administradores, etc. En este caso, el 403 es totalmente apropiado.
    2009-06-03 05: 04: 55Z
  5. Creo que esta es una respuesta bastante inútil. Pensé que el aspecto más importante tiene que ver con si los estados deben usarse únicamente, o si la información de error debe devolverse en la carga útil, o en ambos, etc. Y, CÓMO, cómo se debe agregar la información en la carga útil. El estado específico que se utiliza se está enfocando en un solo aspecto específico de la pregunta.
    2015-02-26 00: 04: 05Z

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:

Por dónde empezar:

 introduce la descripción de la imagen aquí

2XX /3XX:

 introduce la descripción de la imagen aquí

4XX:

 introduce la descripción de la imagen aquí

5XX:

 introduce la descripción de la imagen aquí

    
535
2018-02-17 19: 50: 28Z
  1. 422 Es específicamente una extensión WebDAV. Creo que eso no debería estar aquí.
    2017-07-12 15: 38: 58Z
  2. @ Mario Es idiomático en las API de Ruby on Rails para devolver 422 en respuesta a las condiciones especificadas aquí. Mucho bien siguiendo ese enfoque ya. ¿Para qué reemplazarías los usos de 422?
    2018-02-22 10: 52: 06Z
  3. regular old 400
    2018-04-05 14: 55: 45Z
  4. Gracias. ¿Qué significa "estás haciendo rabia al salir de Internet?"
    2018-12-24 13: 28: 30Z
  5. 2019-01-02 11: 11: 58Z

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

Ambos modos 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 APIs no REST más notorias que se llaman "RESTful".

En este punto (agosto de 2015) 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 incluya 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, es factible, no siempre 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 forma 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
    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/

Problemas principales:

  1. Asegúrate de incluir números de versión para poder cambiar la semántica de la API si es necesario.

  2. Documento...

86
2016-07-21 11: 01: 06Z
  1. Ty. La opción 2 parece SOAP en ropa de descanso ...
    2009-06-03 04: 21: 50Z
  2. No, hacer un túnel de todo a través de un 200 no es nada reparador. Impide que los intermediarios comprendan el resultado de una operación, lo que anulará cualquier forma de almacenamiento en caché, oculta la semántica de la operación e impone la comprensión del contenido del mensaje para procesar un error, lo que infringe la restricción de los mensajes autocontenidos. /div>
    2009-06-04 13: 37: 39Z
  3. Devolver los detalles del error con un 200 podría no ser REST, pero esta es una respuesta útil (si ignora la observación "Ambas formas son tranquilas") ... Un punto más importante puede ser que una API RESTful no sea la mejor opción para el OP.
    2010-06-30 14: 24: 20Z
  4. Parece haber un entendimiento general de que puedes hacer lo que quieras con el protocolo HTTP y seguir siendo "RESTy", eso es falso. Use el protocolo para lo que está escrito, esa es una de las ideas centrales de REST. Por lo tanto, el código de estado debe formar parte de su protocolo.
    2015-11-15 21: 15: 29Z
  5. El punto de los códigos de estado es proporcionar un lenguaje común de comprensión entre diversos lenguajes de programación, marcos y enfoques. Los significados de los códigos de estado son casi universales: su cuerpo personalizado, que inherentemente agrega más complejidad a través de la sintaxis personalizada que los consumidores de API deben conocer, no lo es.
    2018-02-22 10: 56: 25Z

    Recuerde que hay más códigos de estado que los definidos en los RFC HTTP /1.1, el registro de la 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
    2014-10-01 07: 00: 15Z
    1. Hmm, mientras que de un vistazo, "507 Insufficient Storage" parece que podría ser apropiado, no me atrevería a usarlo ya que está pensado como un (bastante específico) Extensión de WebDAV y no una excepción general de "hey you out of space". Aun así, supongo que podrías usarlo.
      2012-05-13 18: 56: 56Z
    2. No, no es en absoluto específico para WebDAV. Hay una razón por la que existe un registro de códigos de estado HTTP.
      2012-05-14 15: 42: 05Z
    3. No estoy de acuerdo con 507 para este propósito. Mi interpretación de 507 es que el servidor no tiene espacio, no que la cuenta está fuera de espacio.
      2013-05-20 20: 02: 00Z
    4. Estoy de acuerdo con Patrick. Los errores 5xx corresponden a errores relacionados con el servidor.
      2013-11-13 02: 03: 25Z
    5. 418: "Soy una tetera", lo que implica que el espacio de almacenamiento es demasiado pequeño (como una tetera es poco) en lugar de grande y por lo tanto está fuera del espacio.
      2013-12-03 15: 49: 38Z

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

      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, definitivamente no es un error del servidor, por lo que se debe evitar 5xx.

          
      22
      2009-06-04 13: 54: 39Z
      1. No estaría de acuerdo. La cuota superada sería un error del servidor (5xx) porque: La solicitud del cliente es válida y habría tenido éxito si fuera de la cuota, lo que descarta la serie 400.
        2012-08-06 02: 03: 46Z
      2. Pero el servidor no ha hecho nada malo.
        2014-09-16 17: 16: 51Z

      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 común distribuida (REST). Consulte "vnd.error", application /vnd.error + json ( https://github.com/blongden/vnd.error) y "Detalles del problema para las API de HTTP", application /problem + json ( https: //tools.ietf.org/html/draft-nottingham-http-problem-05 ).

          
      19
      2013-12-18 09:49: 52Z
      1. Gracias por los enlaces. draft-nottingham-http-problem ahora es un estándar propuesto: datatracker.ietf.org/doc/rfc7807
        2017-07-12 05: 49: 13Z

      Hay dos tipos de errores. Errores de aplicación y errores de HTTP. Los errores de HTTP son solo para que su controlador AJAX sepa que las cosas fueron bien y que no deben usarse para nada más.

      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 Success

      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. Stack Overflow, por ejemplo, envía un objeto con las propiedades response, data y 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 el response es false).

          
      18
      2009-06-03 09: 21: 14Z
      1. 400 también es útil para indicar un problema en la aplicación cliente.
        2017-02-09 17: 08: 28Z

      De acuerdo. 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 útil HTTP. Ya se han establecido 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.

      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 una manera no estándar o de propiedad. Esto tampoco es eficiente: obligará a sus clientes a analizar la carga útil 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.

          
      9
      2013-11-21 17: 38: 01Z
      1. Ya sea que tenga una respuesta exitosa o una respuesta fallida, lo más probable es que analice la respuesta. Si es un error, desea analizarlo para obtener el mensaje de error. Las respuestas de error son generalmente pequeñas y rápidas de analizar. No creo que debamos preocuparnos por tratar de optimizar para evitar analizar las respuestas de error. ¿Desecharía la respuesta de error sin analizarla? No sabio en mi opinión.
        2015-09-16 21: 43: 21Z
      2. Si obtiene un OK 200, puede elegir no analizarlo también, según las reglas de su negocio. El punto no es si lo analizamos en todo momento o no. El punto es la intención, ¿cuál es la intención de 200 OK? Está dañando la intención al enviar mensajes de error envueltos en 200 OK.
        2015-09-18 21: 18: 52Z
      3. "¿cuál es la intención de 200 OK?" - Indicando el éxito de la capa de transporte. La solicitud se ha recibido y respondido correctamente, solo hubo un problema específico de la aplicación que no tiene nada que ver con HTTP. +++ Al revés: el envío de 404 en el mundo REST significa que algo no se encontró, tal vez la URL sea errónea o el recurso a procesar o no se haya encontrado nada más. Sin analizar el mensaje, no puedes. IMHO REST es simplemente concapas planas.
        2018-05-07 02: 27: 57Z
      4. La confusión es la norma. Le proporciona una sintaxis con la que lidiar que se adapta a su línea de razonamiento y le permite concentrarse en la capa empresarial. Acordó el transporte. Las comunicaciones de estado posteriores, que es el propósito en primer lugar, REST no se inventó /propuso simultáneamente con HTTP, llegaron más tarde y simplemente decidieron usar la infraestructura existente para representar a los ESTADOS y sus CAMBIOS.
        2018-05-08 02: 36: 48Z

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

          
      6
      2018-01-08 04: 08: 51Z

      Por favor, apégate a la semántica del protocolo. Use 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 fuera el caso de uso previsto en el protocolo, en primer lugar no tendrían otros códigos de estado.

          
      5
      2016-04-14 06: 42: 33Z

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

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

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

          
      3
      2009-06-03 15: 38: 00Z

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

          
      - 1
      2010-05-06 00: 02: 45Z
      1. ¿Por qué evitar los errores de la serie 5xx cuando son por errores del servidor?
        2012-08-06 02: 06: 39Z
      2. 'cuota de cliente excedida' no es un error del servidor, es una restricción del cliente y debe estar bajo 4xx.
        2013-07-02 08: 33: 09Z
fuente colocada aquí