Les bonnes pratiques de retour de l’API REST

Je cherche des conseils sur les bonnes pratiques en matière de retour d’erreurs d’une API REST. Je travaille sur une nouvelle API afin que je puisse la prendre dans 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 des cas d’erreur, par exemple un client tente d’append une nouvelle ressource mais a dépassé son quota de stockage. Je traite déjà certains cas d’erreur avec les codes d’état HTTP (401 pour l’authentification, 403 pour l’autorisation et 404 pour les URI de requête en règle). J’ai regardé les codes d’erreur HTTP bénis, mais aucune des 400 à 417 ne semble appropriée 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 XML spécifique (c.-à-d. Payez-nous plus et vous obtiendrez le stockage dont vous avez besoin!) Mais je me suis arrêté haussement d’épaules). En outre, j’ai l’impression de diviser les réponses aux erreurs en des cas distincts, car certaines sont basées sur le code d’état HTTP et d’autres sur le contenu.

Alors, quelles sont les recommandations de l’indussortinge? Bonnes pratiques (veuillez expliquer pourquoi!) Et aussi, à partir d’un pov 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 retourner mon erreur d’application avec 200 OK et une charge XML spécifique (c.-à-d. Payez-nous plus et vous obtiendrez le stockage dont vous avez besoin!) Mais je me suis arrêté pour le soapner (/ haussement d’épaules).

Je ne retournerais pas un 200 à moins qu’il n’y ait 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 demande, mais refuse de la satisfaire. L’autorisation ne va pas aider et la demande NE DOIT PAS être répétée. Si la méthode de requête n’était pas HEAD et que le serveur souhaitait rendre publique la raison pour laquelle 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 (non trouvé) peut être utilisé à la place.

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

Quelles autres conditions d’erreur spécifiques avez-vous à l’esprit?

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:

entrer la description de l'image ici

2XX / 3XX:

entrer la description de l'image ici

4XX:

entrer la description de l'image ici

5XX:

entrer la description de l'image ici

Le choix principal est de vouloir traiter le code de statut HTTP comme faisant partie de votre API REST ou non.

Les deux manières fonctionnent bien. Je suis d’accord pour dire que l’une des idées de REST est que vous devez utiliser le code HTTP comme partie de votre API (retournez 200 ou 201 pour une opération réussie et un 4xx ou 5xx en fonction de divers cas d’erreur). , il n’y a pas de police REST. Tu peux faire ce que tu veux. J’ai vu des APIs non-REST beaucoup plus graves 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 lorsque vous utilisez des 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 de statut HTTP fait partie de votre API

  1. Vous devrez choisir avec soin les codes 4xx correspondant à vos conditions d’erreur. Vous pouvez inclure un message de repos, XML ou en texte brut en tant que charge utile comprenant un sous-code et un commentaire descriptif.

  2. Les clients devront utiliser une infrastructure logicielle leur permettant d’accéder au code d’état de 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 indiquant un problème au niveau de l’application.

Le code de statut 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, puis a 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 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 facile pour les clients car le statut de la réponse est toujours au même endroit (pas de sous-code requirejs), pas de limites sur les codes, pas besoin de récupérer 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…

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

Comme d’autres l’ont fait remarquer, le fait d’avoir une entité de réponse dans un code d’erreur est parfaitement acceptable.

Rappelez-vous que les erreurs 5xx sont côté serveur, alias le client ne peut rien changer à sa requête 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é.

Je sais que c’est extrêmement tard pour la fête, mais maintenant, en 2013, nous avons quelques types de médias pour couvrir la gestion des erreurs dans un mode dissortingbué (RESTful) commun. Voir “vnd.error”, application / vnd.error + json ( https://github.com/blongden/vnd.error ) et “Détails des problèmes pour les API HTTP”, application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

Il y a deux sortes d’erreurs. Erreurs d’application et erreurs HTTP. Les erreurs HTTP permettent simplement à votre gestionnaire AJAX de savoir que les choses se sont bien passées et ne doivent pas être utilisées pour autre chose.

Erreur serveur 5xx

 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 manière dont vous concevez vos erreurs d’application dépend de vous. Le débordement de stack, par exemple, envoie un object avec des propriétés de response , de data et de message . La réponse, à mon avis, 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 la response est false ).

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

Envoyer une réponse d’erreur dans une enveloppe HTTP 200 est trompeur et force le client (consommateur api) à parsingr le message, probablement de manière non standard ou propriétaire. Ce n’est pas non plus efficace – vous obligerez vos clients à parsingr la charge HTTP à chaque fois pour comprendre le “vrai” statut de la réponse. 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 professionnelles ou autres. Si l’utilisation de 2xx pour toute réponse était le cas d’utilisation prévu dans le protocole, ils n’auraient pas d’autres codes d’état en premier lieu.

N’oubliez pas les erreurs 5xx ainsi que les erreurs d’application.

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

Sinon, 507 (pas entièrement standard) peut également fonctionner. Je n’utiliserais pas 200 sauf si vous utilisez 200 pour des erreurs en général.

Si le quota du client est dépassé, il s’agit d’une erreur du serveur, évitez 5xx dans cette instance.