334 votos

Error de API REST devolver las buenas prácticas

Estoy buscando orientación sobre las buenas prácticas cuando se trata de devolver errores de una API REST. Estoy trabajando en una nueva API para que yo pueda tomar cualquier dirección a la derecha ahora. Mi tipo de contenido XML en el momento, pero tengo el plan de soporte JSON en el futuro.

Ahora estoy añadiendo algunos casos de error, como por ejemplo un cliente intenta agregar un nuevo recurso, sino que ha superado su cuota de almacenamiento. Ya estoy en el manejo de ciertos casos de error, con códigos de estado HTTP (401 para la autenticación, 403 para la autorización y 404 de la llanura bad request Uri). Me miró por encima del beato de códigos de error HTTP, pero ninguno de los 400-417 rango parece derecho a la aplicación de informe de errores específicos. Así que en un principio estuve tentado de regresar a mi error de aplicación con 200 OK y una determinada carga XML (es decir. Nos pagan más y obtendrás el almacenamiento que usted necesita!) pero me detuve a pensar en ello y parece jabonosa (/encogimiento de hombros en el horror). Además se siente como que estoy dividiendo el error de las respuestas en distintos casos, ya que algunas son de código de estado http impulsado y otros son de contenido impulsada.

Entonces, ¿qué es la multitud recomendación? Buenas prácticas (por favor explique por qué!) y también, desde un cliente de punto de vista, ¿qué tipo de control de errores en la API de REST hace la vida más fácil para el código de cliente?

140voto

Rich Apodaca Puntos 7327

Así que en un principio estuve tentado de regresar a mi error de aplicación con 200 OK y una determinada carga XML (es decir. Nos pagan más y obtendrás el almacenamiento que usted necesita!) pero me detuve a pensar en ello y parece jabonosa (/encogimiento de hombros en el horror).

Yo no volvería a 200 a menos que realmente no había nada de malo con la solicitud. De RFC2616, 200 significa "la solicitud se ha realizado correctamente."

Si el cliente de la cuota de almacenamiento ha sido superado (por cualquier razón), me gustaría volver con un plan 403 (Prohibido):

El servidor entendido la petición, pero se niega a cumplirla. La autorización no será de ayuda y la solicitud NO DEBE repetirse. Si el método de solicitud no fue de la HEAD y el servidor quiere hacer público el porqué de la petición no ha sido cumplido, se DEBE describir la razón de la negativa de la entidad. Si el servidor no desea que esta información esté disponible para el cliente, el código de estado 404 (No Encontrado) puede utilizarse en su lugar.

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

¿Qué otras condiciones de error específico ¿tiene usted en mente?

60voto

Larry K Puntos 16266

La principal opción es hacer que usted desea para tratar el código de estado HTTP, como parte de su Api REST o no.

Ambas formas funcionan bien.

El código de Estado HTTP que es parte de su api

  1. Usted tendrá que tomar cuidadosamente 4xx códigos que se ajuste a sus condiciones de error. Puede incluir un mensaje xml como la carga que incluye un sub-código y un comentario descriptivo.

  2. Los clientes necesitan utilizar un framework de software que les permite obtener en HTTP estado de nivel de código. Generalmente, capaz de hacer -, no siempre es sencillo.

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

El código de Estado HTTP que NO es parte de su api

  1. El código de estado HTTP que siempre será de 200 si su aplicación recibe la solicitud y, a continuación, respondió (tanto éxito y casos de error)

  2. TODAS sus respuestas deben incluir la "envoltura" o "cabecera" de la información. Normalmente algo como:

    envelope_ver: 1.0
    estado: # uso de códigos que te gusta. Reserva un código para el éxito. 
    msg: "ok" # Una cadena humana que refleja el código. Útil para la depuración.
    datos: ... # Los datos de la respuesta, si la hay.
  3. Este método puede ser más fácil para los clientes desde el estado para la respuesta está siempre en el mismo lugar (no sub-códigos necesarios), no hay límites en los códigos, no hay necesidad de recuperar la HTTP estado de nivel de código.

He aquí un post con una idea similar: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Cuestiones principales:

1) asegúrese de incluir los números de versión para posteriormente puede cambiar la semántica de la api, si es necesario.

2) el Documento...

Larry

36voto

Julian Reschke Puntos 12698

Recuerda hay más códigos de estado que los definidos en el RFC2616, el registro IANA está en http://www.iana.org/assignments/http-status-codes. Para el caso mencionado Código de estado 507 suena bien.

20voto

serialseb Puntos 5509

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

Recuerde que 5xx errores del servidor, alias el cliente no puede cambiar nada a su solicitud para realizar la solicitud de pase. Si se supera la cuota del cliente, es definitivamente no es un error de servidor, así que debe evitarse 5xx.

10voto

aleemb Puntos 12138

Hay dos tipos de errores. Aplicación de los errores y de los errores HTTP. HTTP errores son sólo para que su AJAX de controlador de saber que las cosas fueron bien y no debe ser utilizado para otra cosa.

5xx De Error De 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, el diseño de los errores de aplicación es realmente depende de usted. Stack Overflow, por ejemplo, envía un objeto con response, data y message propiedades. La respuesta creo que contiene true o false para indicar si la operación fue exitosa (normalmente para las operaciones de escritura). Los datos que contiene la carga (normalmente para las operaciones de lectura) y el mensaje contiene metadatos adicionales o mensajes útiles (tales como mensajes de error cuando la response es false).

Iteramos.com

Iteramos es una comunidad de desarrolladores que busca expandir el conocimiento de la programación mas allá del inglés.
Tenemos una gran cantidad de contenido, y también puedes hacer tus propias preguntas o resolver las de los demás.

Powered by:

X