Question Erreur API REST renvoyer les bonnes pratiques [fermé]


Je suis à la recherche de 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 en 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 d'état HTTP (401 pour l'authentification, 403 pour l'autorisation et 404 pour les URI de demande non valide). J'ai regardé par-dessus les codes d'erreur HTTP bénis, mais aucune de la gamme 400-417 semble juste pour signaler des erreurs spécifiques à l'application. Donc, au début, j'ai été tenté de retourner mon erreur d'application avec 200 OK et une charge utile XML spécifique (par exemple Payez-en plus et vous aurez le stockage dont vous avez besoin!) Mais je me suis arrêté pour y penser. hausser les épaules dans l'horreur). En outre, il semble que je divise les réponses d'erreur en cas distincts, car certains sont pilotés par le code d'état http et d'autres par le contenu.

Alors, quelles sont les recommandations de l'industrie? Bonnes pratiques (veuillez expliquer pourquoi!) Et aussi, à partir d'un client pov, quel type de gestion des erreurs dans l'API REST rend la vie plus facile pour le code client?


545
2018-06-03 03:39


origine


Réponses:


Donc, au début, j'ai été tenté de retourner mon erreur d'application avec 200 OK et une charge utile XML spécifique (par exemple Payez-en plus et vous aurez le stockage dont vous avez besoin!) Mais je me suis arrêté pour y penser. hausser les épaules dans l'horreur).

Je ne retournerais pas un 200 sauf s'il n'y avait vraiment rien de mal à la demande. De RFC2616, 200 signifie "la requête 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 requête, mais refuse de l'exécuter. L'autorisation n'aidera pas et la demande NE DEVRAIT PAS être répétée. Si la méthode de requête n'était pas HEAD et que le serveur souhaite rendre public pourquoi la requête n'a pas été satisfaite, il DEVRAIT décrire la raison du refus dans l'entité. Si le serveur ne souhaite pas mettre cette information à la disposition du client, le code d'état 404 (Introuvable) peut être utilisé à la place.

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

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


196
2018-06-03 04:08



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:

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



Le choix principal est de vouloir traiter le code d'état HTTP dans le cadre de votre API REST ou non.

Les deux façons fonctionnent bien. Je suis d'accord que, à proprement parler, l'une des idées de REST est que vous devriez utiliser le code d'état HTTP comme une partie de votre API (retour 200 ou 201 pour une opération réussie et 4xx ou 5xx selon différents cas d'erreur). , il n'y a pas de police REST. Tu peux faire ce que tu veux. J'ai vu beaucoup plus d'API non-REST flagrantes s'appeler "RESTful".

À ce point (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 non-200 et le nombre de 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, de xml ou de texte brut en tant que charge utile comprenant 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 (à la fois les cas de réussite et d'erreur)

  2. TOUTES vos réponses doivent inclure des informations "enveloppe" ou "en-tête". Typiquement quelque chose comme:

    envelope_ver: 1.0
    status: # utilise les codes que tu aimes. Réservez un code pour le succès.
    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 puisque le statut de la réponse est toujours au même endroit (aucun sous-code requis), aucune limite sur les codes, pas besoin d'aller chercher le code d'état au niveau HTTP.

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

Principaux problèmes:

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


80
2018-06-03 04:13



Rappelez-vous qu'il existe plus de codes de statut que ceux définis dans les RFC HTTP / 1.1, le registre de l'IANA est à http://www.iana.org/assignments/http-status-codes. Pour le cas que vous avez mentionné le code d'état 507 sonne bien.


40
2018-06-03 05:46



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

Rappelez-vous que les erreurs 5xx sont côté serveur, alias le client ne peut rien changer à sa demande pour faire passer la requête. Si le quota du client est dépassé, ce n'est définitivement pas une erreur de serveur, donc 5xx devrait être évité.


22
2018-06-04 13:54



Je sais que c'est très tard pour la fête, mais maintenant, en 2013, nous avons quelques types de médias pour traiter les erreurs dans un mode distribué commun (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 / problème + json (https://tools.ietf.org/html/draft-nottingham-http-problem-05).


19
2017-12-18 09:49



Il y a 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 devraient pas être utilisées pour autre chose.

5xxerreur 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 )

2xx succès

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 avec response, data et message Propriétés. La réponse que je crois contient true ou false pour indiquer 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 lorsque le response est false).


17
2018-06-03 09:21



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. Ils sont déjà des codes universels établis qui transmettent le statut de réponse, et donc, pour être vraiment RESTful, les applications doivent utiliser ce cadre pour communiquer le statut de réponse.

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


9
2017-11-21 17:38



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/fr/docs/basics/conseils-codes


6
2017-10-23 05:39