L'erreur de l'API REST renvoie les bonnes pratiques [fermé]

Je recherche des conseils sur les bonnes pratiques en matière de retour d'erreurs à partir d'une API REST. Je travaille sur une nouvelle API afin que je puisse prendre n'importe quelle direction dès maintenant. Mon type de contenu est XML pour le moment, mais je prévois de prendre en charge JSON à l'avenir.

J'ajoute maintenant quelques cas d'erreur, comme par exemple un client tente d'ajouter une nouvelle ressource mais a dépassé son quota de stockage. Je gère déjà certains cas d'erreur avec des codes de statut HTTP (401 pour l'authentification, 403 pour l'autorisation et 404 pour les URI de demande non valides). J'ai regardé les codes d'erreur HTTP bénis, mais aucun de la plage 400-417 ne semble correct de signaler des erreurs spécifiques à l'application. Donc, au début, j'ai été tenté de renvoyer mon erreur d'application avec 200 OK et une charge utile XML spécifique (c'est-à-dire. Payez-nous plus et vous obtiendrez le stockage dont vous avez besoin!) Mais je me suis arrêté pour y penser et cela semble savonneux (/ hausser les épaules avec horreur). De plus, j'ai l'impression de diviser les réponses d'erreur en cas distincts, car certains sont basés sur le code de statut http et d'autres sur le contenu.

Alors, quelles sont les recommandations de l'industrie? Bonnes pratiques (expliquez pourquoi!) Et aussi, à partir d'un point de vue client, quel type de gestion des erreurs dans l'API REST facilite la vie du code client?

Donc, au début, j'ai été tenté de renvoyer mon erreur d'application avec 200 OK et une charge utile XML spécifique (c'est-à-dire. Payez-nous plus et vous obtiendrez le stockage dont vous avez besoin!) Mais je me suis arrêté pour y penser et cela semble savonneux (/ hausser les épaules avec horreur).

Je ne retournerais pas 200 sauf s'il n'y avait vraiment rien de mal à la demande. De RFC2616 , 200 signifie "la demande a réussi."

Si le quota de stockage du client a été dépassé (pour une raison quelconque), je retournerais un 403 (interdit):

Le serveur a compris la demande, mais refuse de la satisfaire. L'autorisation n'aidera pas et la demande NE DEVRAIT PAS être répétée. Si la méthode de demande n'était pas HEAD et que le serveur souhaite rendre public pourquoi la demande n'a pas été satisfaite, il DEVRAIT décrire la raison du refus dans l'entité. Si le serveur ne souhaite pas mettre ces informations à la disposition du client, le code d'état 404 (Not Found) peut être utilisé à la place.

Cela indique au client que la demande était OK, mais qu'elle a échoué (quelque chose qu'un 200 ne fait pas). Cela vous donne également la possibilité d'expliquer le problème (et sa solution) dans le corps de réponse.

Quelles autres conditions d'erreur spécifiques aviez-vous en tête?

Une excellente ressource pour choisir le code d'erreur HTTP correct pour votre API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Un extrait de l'article:

Où commencer:

2XX / 3XX:

4XX:

5XX:

Le choix principal est si vous souhaitez traiter le code d'état HTTP comme faisant partie de votre API REST ou non.

Les deux méthodes fonctionnent bien. Je suis d'accord que, strictement parlant, l'une des idées de REST est que vous devez utiliser le code d'état HTTP dans le cadre de votre API (renvoyer 200 ou 201 pour une opération réussie et un 4xx ou 5xx selon divers cas d'erreur.) Cependant , il n'y a pas de police REST. Tu peux faire ce que tu veux. J'ai vu des API non REST beaucoup plus flagrantes être appelées «RESTful».

À ce stade (août 2015), je vous recommande d'utiliser le code d'état HTTP dans le cadre de votre API. Il est maintenant beaucoup plus facile de voir le code de retour lors de l'utilisation de frameworks que par le passé. En particulier, il est maintenant plus facile de voir le cas de retour non-200 et le corps des réponses non-200 que par le passé.

Le code d'état HTTP fait partie de votre API

1. Vous devrez choisir soigneusement les codes 4xx qui correspondent à vos conditions d'erreur. Vous pouvez inclure un message de repos, xml ou texte en clair comme charge utile qui comprend un sous-code et un commentaire descriptif.

2. Les clients devront utiliser une infrastructure logicielle qui leur permettra d'obtenir le code d'état au niveau HTTP. Habituellement faisable, pas toujours simple.

3. Les clients devront faire la distinction entre les codes d'état HTTP qui indiquent une erreur de communication et vos propres codes d'état qui indiquent un problème au niveau de l'application.

Le code d'état HTTP ne fait PAS partie de votre API

1. Le code d'état HTTP sera toujours 200 si votre application a reçu la demande et a ensuite répondu (cas de réussite et d'erreur)

2. TOUTES vos réponses doivent inclure des informations «enveloppe» ou «en-tête». Généralement, quelque chose comme:

   enveloppe_ver: 1.0
   status: # utilisez les codes que vous aimez. Réservez un code pour réussir.
   msg: "ok" # Une chaîne humaine qui reflète le code. Utile pour le débogage.
   data: ... # Les données de la réponse, le cas échéant.

3. Cette méthode peut être plus simple pour les clients car le statut de la réponse est toujours au même endroit (aucun sous-code nécessaire), aucune limite sur les codes, pas besoin de récupérer le code de statut au niveau HTTP.

Voici un article avec une idée similaire: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Problèmes principaux:

1. Assurez-vous d'inclure les numéros de version afin de pouvoir modifier ultérieurement la sémantique de l'API si nécessaire.

2. Document...

N'oubliez pas qu'il y a plus de codes d'état que ceux définis dans les RFC HTTP / 1.1, le registre IANA se trouve à http://www.iana.org/assignments/http-status-codes . Dans le cas où vous avez mentionné le code d'état 507, cela semble juste.

Comme d'autres l'ont souligné, il est parfaitement permis d'avoir une entité de réponse dans un code d'erreur.

N'oubliez pas que les erreurs 5xx sont côté serveur, c'est-à-dire que le client ne peut rien changer à sa demande pour que la demande soit acceptée. Si le quota du client est dépassé, ce n'est définitivement pas une erreur de serveur, donc 5xx doit être évité.

Il existe deux sortes d'erreurs. Erreurs d'application et erreurs HTTP. Les erreurs HTTP sont juste pour faire savoir à votre gestionnaire AJAX que les choses se sont bien passées et ne doivent pas être utilisées pour autre chose.

5xx erreur du serveur

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 )

Succès 2xx

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)

Cependant, la façon dont vous concevez vos erreurs d'application dépend vraiment de vous. Stack Overflow par exemple envoie un objet response, dataet les messagepropriétés. Je crois que la réponse contient trueou falseindique si l'opération a réussi (généralement pour les opérations d'écriture). Les données contiennent la charge utile (généralement pour les opérations de lecture) et le message contient des métadonnées supplémentaires ou des messages utiles (tels que des messages d'erreur lorsqu'ils le responsesont false).

Je sais que c'est très tard pour la fête, mais maintenant, en 2013, nous avons quelques types de médias pour couvrir le traitement des erreurs de manière distribuée (RESTful). Voir "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) et "Détails du problème pour les API HTTP", application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

D'accord. La philosophie de base de REST est d'utiliser l'infrastructure Web. Les codes d'état HTTP sont le cadre de messagerie qui permet aux parties de communiquer entre elles sans augmenter la charge utile HTTP. Ce sont des codes universels déjà établis transmettant l'état de réponse, et donc, pour être vraiment RESTful, les applications doivent utiliser ce cadre pour communiquer l'état de réponse.

L'envoi d'une réponse d'erreur dans une enveloppe HTTP 200 est trompeur et oblige le client (consommateur api) à analyser le message, très probablement d'une manière non standard ou propriétaire. Ce n'est pas non plus efficace - vous obligerez vos clients à analyser la charge utile HTTP à chaque fois pour comprendre le statut de réponse «réel». Cela augmente le traitement, ajoute de la latence et crée un environnement permettant au client de faire des erreurs.

Modéliser votre API sur les «meilleures pratiques» existantes pourrait être la voie à suivre. Par exemple, voici comment Twitter gère les codes d'erreur https://developer.twitter.com/en/docs/basics/response-codes

Veuillez vous en tenir à la sémantique du protocole. Utilisez 2xx pour les réponses réussies et 4xx, 5xx pour les réponses d'erreur - que ce soit vos exceptions commerciales ou autres. Si l'utilisation de 2xx pour n'importe quelle réponse avait été le cas d'utilisation prévu dans le protocole, ils n'auraient pas d'autres codes d'état en premier lieu.

N'oubliez pas non plus les erreurs 5xx pour les erreurs d'application.

Dans ce cas, qu'en est-il du 409 (conflit)? Cela suppose que l'utilisateur peut résoudre le problème en supprimant les ressources stockées.

Sinon, le 507 (pas entièrement standard) peut également fonctionner. Je n'utiliserais pas 200 à moins que vous n'utilisiez 200 pour les erreurs en général.

Si le quota client est dépassé, c'est une erreur de serveur, évitez 5xx dans ce cas.