Je vais décrire un exemple:
je commence à créer une API pour un magasin de pâtisserie. L'API permettra aux utilisateurs de rechercher dans leur catalogue des produits de cuisson, tels que les biscuits faits maison aux pépites de chocolat et à la menthe api.examplebakery.com/search?q=.....
.
Quelqu'un l'utilise pour rechercher un produit nommé pineapple-banana flavoured cookies
et ne trouvera évidemment aucun résultat.
Cela devrait-il être retourné comme une erreur? La recherche n’a pas échoué, l’API a effectué la recherche et a conclu qu’aucun cookie n’était trouvé. L'API ne doit pas revenir 404
, car l'API a bien été trouvée.
rest
http-response
Berry M.
la source
la source
Réponses:
Lorsqu'il y a des résultats, le résultat est une liste (JSON, basée sur votre commentaire). Pour les requêtes sans résultat, le résultat devrait être exactement le même. La liste simple contient 0 éléments.
Donc, si votre réponse est normalement ceci:
Ensuite, pour une requête avec 0 résultats, cela devrait être ceci:
Si vous incluez également des métadonnées sur le nombre de "pages" de résultats, des liens vers ces "pages", etc., je vous suggérerais alors de définir 1 "page".
Le statut HTTP doit être le même que lorsqu'il y a des résultats -
200 OK
.204 No Content
Cela peut aussi sembler être une option, mais ce n’est pas parce que vous retournez en fait du "contenu" - la liste vide. Si vous estimez qu'une liste vide ne compte pas comme "contenu", si vous modifiez ensuite la réponse pour proposer des suggestions orthographiques? Le noyau de la réponse sera toujours une liste vide, mais maintenant il y a encore plus de "contenu".Pour plus d'informations utiles sur les codes d'état HTTP, la réponse de jpmc26 mérite d'être lue.
la source
Chaque fois que vous choisissez un code HTTP, vous devez toujours poser cette question:
Décidez toujours dans quelle plage votre code de réponse doit être placé en premier. Faire si rapidement élimine un grand nombre de codes de réponse en tant qu'options, et (peut-être plus important encore) il est beaucoup plus simple de suivre la sémantique des codes. Voir les sections de début de la documentation du code HTTP pour des explications sur ce que chaque catégorie de codes représente.
Dans ce cas, le client a demandé une liste de résultats avec un filtre provenant d'un noeud final existant valide et a l'autorisation d'y accéder. Le serveur a pu traiter la demande et déterminer les données appropriées à renvoyer (aucun élément). La demande a donc abouti. Il se trouve que le filtre qu'ils ont donné a filtré tous les résultats. Il n'appartient pas au serveur de déterminer si c'est ce que le client voulait ou non, car cela peut être un résultat attendu pour certains clients. S'il y a un problème pour le code client, c'est au client qu'il incombe de déterminer, vérifier et gérer de manière appropriée. Donc, c'est clairement 2xx.
Maintenant, la question est: "Quel 2xx?" Cela dépend de la façon dont vous souhaitez que le serveur réponde.
Les autres ne sont pas applicables du tout:
Il doit donc être soit 200, soit 204, et 200 entraînera probablement un code client plus simple et plus robuste (en particulier si vous utilisez une structure de réponse cohérente contenant une liste vide).
la source
null
une liste dans le cas contraire), vous ne récolterez pas les avantages de la cohérence, même avec 200. Cependant, ce que je décris utilise une réponse cohérente avec la structure normale et contenant une liste vide dans laquelle la liste des résultats devrait normalement aller. 204 enlève toute possibilité d'avoir une réponse aussi cohérente. De même, même dans les bibliothèques de clients HTTP dotées de fonctions pratiques, vous devez (généralement?) Faire un appel explicite pour analyser JSON.L'utilisation de 404 pour indiquer "votre requête a été traitée mais il n'y a pas eu de correspondance" est horrible pour les raisons suivantes:
flux conditionnel basé sur la gestion des exceptions (c'est-à-dire forcer un résultat non exceptionnel à créer et à gérer une exception dans le client qui peut être non performante et gênante)
ambiguïté entre la 'vraie' page non trouvée, vous avez tapé les erreurs erronées au point final
Ce qu'il faut retenir, c'est qu'il y a toujours un client pour désérialiser le message et que ce qu'il retourne est important; pas la sérialisation.
Si le client doit renvoyer null, utilisez la sérialisation de null. Si le client doit renvoyer un tableau vide, utilisez [], s'il envoie une erreur, utilisez 500 et transmettez le message d'erreur.
la source
Au-delà de la très bonne réponse de @ Ewan:
Si la requête est du genre qui renvoie un ensemble de résultats, alors l'ensemble vide est logiquement tout aussi approprié qu'un ensemble de un ou de plusieurs. De manière générale, pour les raisons évoquées par @Ewan, modifier le jeu vide en une erreur fait plus de tort que de mal, ce qui est tout simplement inutile.
Si la requête est du type qui recherche et renvoie un singleton spécifique (que l'on s'attend à trouver, par exemple, la correspondance exacte par id), alors non trouvé est une réponse possible logiquement appropriée.
la source
Vous supposez que le code doit prendre une mesure spéciale lorsqu'aucune donnée n'est renvoyée, mais ce n'est peut-être pas le cas. Le code peut simplement rechercher un nombre de produits ou ajouter les résultats à une liste ou à un nombre important d'éléments. Vous ne devriez donner à un utilisateur une "erreur" que s'il y a réellement une erreur.
la source
Lorsque j'utilise une API, en tant que client, je dois gérer des cas de "réussite" différents des cas "d'erreur". Je n'ai pas le choix là-bas. Par conséquent, vous devez renvoyer une erreur dans les situations que le client souhaite traiter différemment et réussir dans les situations que le client souhaite traiter de la même manière.
Si je fais une requête qui pourrait théoriquement renvoyer un nombre quelconque de résultats, zéro, un, deux cents, etc., vous devriez alors renvoyer "succès" chaque fois que l'API fournit la liste complète de tous les résultats. Et peut-être dans les cas où il y a plusieurs résultats, vous avez renvoyé une liste partielle des résultats pour éviter une taille excessive, et il existe un moyen convenu d'obtenir les autres résultats. En effet, en tant que client, je souhaite souvent gérer le cas de résultats nuls, comme le cas de résultats plus nombreux. Je pourrais le traiter différemment, mais je ne veux pas être obligé de le faire.
Il en va différemment dans le cas où je cherche une valeur. J'attends exactement un résultat, la valeur que je recherche. Et j'ai besoin de ce résultat pour continuer ce que je veux faire de manière significative. Ici, il est beaucoup plus acceptable de renvoyer un statut 404 pour le cas où aucune valeur n’y figure, car j’ai quand même besoin de traiter ce cas différemment.
Récapitulatif: si le client attend un nombre quelconque de résultats, allant de zéro à un nombre élevé, renvoyez "succès" si tous les résultats sont livrés, même si le nombre est zéro. Si le client attend exactement un résultat, retournez success si le résultat est trouvé et une erreur si le résultat est introuvable.
la source