“Aucun résultat” doit-il être une erreur dans une réponse RESTful?

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

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:

{
    "results": [
        {
            "name": "Pancakes",
            ....
        },
        {
            "name": "French Fries",
            ....
        }
    ]
}

Ensuite, pour une requête avec 0 résultats, cela devrait être ceci:

{
    "results": []
}

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

Chaque fois que vous choisissez un code HTTP, vous devez toujours poser cette question:

Que peut / voudra / devrait tout client arbitraire faire avec la réponse?

1. Le client doit-il toujours traiter la réponse comme un échec? Ensuite, vous voulez 4xx ou 5xx, selon que le problème concerne l'entrée du client ou les processus du serveur.
2. Le client doit-il faire une demande ailleurs? Alors 3xx est pour vous.
3. Le serveur a-t-il fait ce que le client a demandé (réussi)? C'est 2xx.

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.

• Allez-vous renvoyer une représentation d'une liste vide, comme le décrivent d' autres réponses ? Si tel est le cas, vous voulez 200. 200 signifie que le serveur n'a rencontré aucun problème et a une représentation des résultats à utiliser par le client. C’est probablement le moyen le plus pratique de répondre pour vos clients, qui peuvent simplement analyser la réponse, qu’il obtienne des résultats ou non, puis déterminer comment gérer eux-mêmes une liste vide.
• 204 n’est pas sémantiquement faux ici, mais vous auriez à répondre sans corps du message . Cela signifie que tout le code client devrait explicitement rechercher différents codes HTTP (ou au moins l'absence de corps de message) et les gérer séparément. C'est peu pratique et plus susceptible de conduire à des clients mal élevés.

Les autres ne sont pas applicables du tout:

• 201 est hors de question. Vous n'avez créé aucune ressource persistante et vous ne rendez pas d'emplacement à une ressource créée.
• 202 est hors de question. La demande est faite; ce n'est pas un traitement en arrière-plan.
• 203 signifie que la réponse a été modifiée entre le serveur faisant autorité et le client. Votre interface RESTful est le serveur faisant autorité, ce qui ne s'applique pas ici.
• 205 n'a pas de sens. Vous n'avez pas besoin du client pour effacer ou actualiser quoi que ce soit.
• 206 semble être conçu pour renvoyer une ressource volumineuse sur plusieurs réponses. Il faut également que le client demande une partie du contenu dans les en-têtes (la pagination via des chaînes de requête ne peut donc pas être qualifiée). Non applicable ici.

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

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.

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.

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.

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.