Est-il raisonnable que les ressources REST soient singulières et plurielles?

Je me demandais si, plutôt qu'une disposition plus traditionnelle comme celle-ci:

api/Products
GET // gets product(s) by id
PUT // updates product(s) by id
DELETE // deletes (product(s) by id
POST // creates product(s)

Serait-il plus utile d'avoir un singulier et un pluriel, par exemple:

api/Product
GET // gets a product by id
PUT // updates a product by id
DELETE // deletes a product by id
POST // creates a product

api/Products
GET // gets a collection of products by id
PUT // updates a collection of products by id
DELETE // deletes a collection of products (not the products themselves)
POST // creates a collection of products based on filter parameters passed

Donc, pour créer une collection de produits, vous pouvez faire:

POST api/Products {data: filters} // returns api/Products/<id>

Et puis, pour le référencer, vous pourriez faire:

GET api/Products/<id> // returns array of products

À mon avis, le principal avantage de procéder de cette façon est qu'il permet une mise en cache facile des collections de produits. On pourrait, par exemple, mettre une durée de vie d'une heure sur des collections de produits, réduisant ainsi considérablement les appels sur un serveur. Bien sûr, je ne vois actuellement que le bon côté de faire les choses de cette façon, quel est l'inconvénient?

rest

— Eva
source

Réponses:

Souvent, lorsqu'une collection va être le moyen le plus utile d'interagir avec votre API, il peut être plus simple de considérer un seul comme une collection avec un seul membre. Ensuite, si plus tard vous souhaitez exposer une API pour interagir avec des célibataires, il suffit de sous les couvertures de convertir le single transmis en collection avec ce membre, puis il utilise la mise en œuvre identique de l'autre API.

Je suppose que ce que je dis ici est que si vous voulez que les collections soient un mécanisme d'interaction, commencez par l'API de collection uniquement et une fois le système terminé, l'autre API est une simple attache auxiliaire au niveau de la couche d'interface que vous pouvez ajouter ensuite si vous le trouvez particulièrement utile. Vous pouvez cependant trouver que son utilité est suffisamment minime pour appliquer YAGNI et utiliser simplement l'interface de collections pour les quelques instances de singles que vous souhaitez.

— Jimmy Hoffa
source

Bien que je sois d'accord avec votre sentiment, en supposant que nous utilisons l'exemple ci-dessus, étant donné que l'API POST / Produits serait utilisé pour passer des paramètres de filtre de collecte et non des données pour la création de nouveaux produits, quelle serait une façon raisonnable de créer un nouveau produit sans api / Produit?

— Eva

@Evan Pourquoi ne peut-on pas publier sur api / Produits insérer plusieurs (ou une collection d'un) Produits? Cela me semble le plus logique. Peut-être publier des produits / filtres pour créer des filtres, ou obtenir s'ils sont une tâche de récupération et non de création.

— Jimmy Hoffa

Merci pour l'élaboration, Jimmy. La raison pour laquelle je ne le voyais pas de cette façon était que je considérais, dans l'exemple ci-dessus, la collection comme une ressource identifiée en soi. Sur un backend, api / Product peut être "Product" et api / Products donc "ProductCollection". Cependant, après un certain examen, je pense qu'il serait peut-être préférable de faire abstraction du fait que tous loin de l'API, comme dans votre suggestion ... maintenant à la vraie question, vous êtes-vous éloigné de cet arrêt de camion sur le chemin de la Thaïlande, ou avez-vous quitté dans le coffre d'une voiture?

— Eva

@Evan Je vais vous donner deux indices: Seagulls.

— Jimmy Hoffa

L'inconvénient est que le programme appelant doit également pluraliser le nom de la ressource, ce qui peut être délicat pour les langues clientes qui n'ont pas de mécanismes de pluralisation intégrés. Si vous le laissez au singulier, il est plus facile pour l'appelant d'automatiser la génération de code pour sa bibliothèque cliente.

Si vous souhaitez atténuer cela, vous pouvez générer vous-même les SDK pour votre service REST. Ou, vous pouvez simplement être opiniâtre et traiter les plaintes :)

— Chris McCall
source