Comment dois-je implémenter un verbe COUNT dans mon service web RESTful ?

Question

J'ai écrit un service web RESTful qui prend en charge les opérations CRUD standard et qui peut renvoyer un ensemble d'objets correspondant à certains critères (un verbe SEARCH), mais j'aimerais ajouter un verbe COUNT d'ordre supérieur, afin que les clients puissent compter les ressources correspondant aux critères de recherche sans avoir à les récupérer toutes.

Quelques options me viennent à l'esprit :

• Ignorer la spécification HTTP et renvoyer le nombre d'objets dans le corps de la réponse d'une requête HEAD.

• Dupliquer la logique du verbe SEARCH, mais en effectuant une requête HEAD au lieu d'une requête GET. Le serveur coderait alors le nombre d'objets dans un en-tête de réponse.

• Définition d'une nouvelle méthode HTTP, COUNT, qui renvoie le nombre d'objets dans le corps de la réponse.

Je préférerais l'API de la première approche, mais je dois supprimer cette option parce qu'elle n'est pas conforme. La deuxième approche semble la plus correcte d'un point de vue sémantique, mais l'API n'est pas très pratique : les clients devront s'occuper des en-têtes de réponse, alors que la plupart du temps ils veulent pouvoir faire quelque chose de simple comme response.count . Je penche donc pour la troisième approche, mais je suis préoccupé par les problèmes potentiels liés à la définition d'une nouvelle méthode HTTP.

Que feriez-vous ?

Answer 1

L'objectif principal du repos est de définir un ensemble de ressources avec lesquelles vous interagissez à l'aide de verbes bien définis. Vous devez donc éviter de définir vos propres verbes. Le nombre de ressources doit être considéré comme une ressource différente, avec sa propre uri que vous pouvez simplement GET. Par exemple :

GET resources?crit1=val1&crit2=val2

renvoie la liste des ressources et

GET resources/count?crit1=val1&crit2=val2

Une autre option consiste à utiliser le conneg : par exemple. Accept: text/uri-list renvoie la liste des ressources et Accept: text/plain ne renvoie que le compte

Answer 2

Vous pouvez utiliser HEAD sans enfreindre la spécification HTTP et vous pouvez indiquer le nombre en utilisant un en-tête HTTP Range dans la réponse :

HEAD /resource/?search=lorem

Réponse du service, en supposant que vous renvoyez les 20 premiers résultats par défaut :

...
Content-Range: resources 0-20/12345
...

De cette manière, vous transférez la quantité de ressources au client dans l'en-tête du message de réponse, sans avoir à renvoyer le corps du message.

Mise à jour :
La solution proposée Yannick Loiseau fonctionnera parfaitement. Je voulais simplement vous proposer une autre approche qui peut être utilisée pour obtenir ce dont vous avez besoin sans avoir à définir une nouvelle ressource de verbe.

Vous pouvez utiliser GET et ajouter le décompte dans le corps du message. Ensuite, si votre API permet aux clients de demander une fourchette de résultats, vous pouvez l'utiliser pour limiter la taille du corps du message à un minimum (puisque vous ne voulez que le décompte). Une façon de procéder serait de demander une plage vide (de 0 à 0), par exemple :

GET /resource/?search=lorem&range=0,0

Le service pourrait alors répondre comme suit, en indiquant qu'il y a 1234 ressources correspondantes dans l'ensemble des résultats :

<?xml version="1.0" encoding="UTF-8" ?>
<resources range="0-0/1234" />

Answer 3

Ignorer la spécification HTTP et renvoyer le nombre d'objets dans le corps de la réponse d'une requête HEAD.

C'est une très mauvaise idée. Elle pourrait ne pas fonctionner simplement parce que vous pourriez avoir des intermédiaires qui n'ignorent pas la spécification HTTP.

Définition d'une nouvelle méthode HTTP, COUNT, qui renvoie le nombre d'objets dans le corps de la réponse.

Cette approche ne pose aucun problème. HTTP est extensible et vous pouvez définir vos propres verbes. Certains pare-feu l'interdisent, mais ils interdisent généralement aussi POST et DELETE et l'en-tête X-HTTP-Method-Override est largement pris en charge.

Une autre option consiste à ajouter un paramètre de requête à votre URL, quelque chose comme : ?countOnly=true