Dois-je utiliser la convention de nom au singulier ou au pluriel pour les ressources REST?

Question

Certains services RESTful utilisent des URI de ressources différentes pour la mise à jour, la récupération et la suppression, comme :

• Créer - en utilisant /ressources avec la méthode POST (en observant le pluriel) dans certains cas en utilisant /ressource (singulier)
• Mettre à jour - en utilisant /ressource/123 avec la méthode PUT
• Obtenir - en utilisant /ressource/123 avec la méthode GET

Je suis un peu confus à propos de cette convention de nommage d'URI. Devrions-nous utiliser le pluriel ou le singulier pour la création de ressources ? Quels critères devraient être pris en compte pour décider de cela ?

Answer 1

Pour moi, il vaut mieux avoir un schéma que vous pouvez mapper directement vers du code (facile à automatiser), principalement parce que le code va être présent aux deux extrémités.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data)

Answer 2

La prémisse d'utiliser /resources est qu'elle représente "toutes" les ressources. Si vous faites un GET /resources, vous retournerez probablement l'ensemble de la collection. En faisant un POST sur /resources, vous ajoutez à la collection.

Cependant, les ressources individuelles sont disponibles à /resource. Si vous faites un GET /resource, vous obtiendrez probablement une erreur, car cette demande n'a aucun sens, alors que /resource/123 a tout à fait du sens.

Utiliser /resource au lieu de /resources est similaire à ce que vous feriez si vous travailliez, disons, avec un système de fichiers et une collection de fichiers et que /resource est le "répertoire" avec les fichiers individuels 123, 456 dedans.

Aucune des deux façons n'est bonne ou mauvaise, allez avec ce que vous préférez.

Answer 3

Je ne vois pas non plus l'intérêt de faire cela et je pense que ce n'est pas la meilleure conception d'URI. En tant qu'utilisateur d'un service RESTful, je m'attends à ce que la ressource de la liste ait le même nom, que j'accède à la liste ou à une ressource spécifique 'dans' la liste. Vous devriez utiliser les mêmes identifiants que vous souhaitiez utiliser la ressource de liste ou une ressource spécifique.

Answer 4

Pourquoi ne pas suivre la tendance prédominante des noms de tables de base de données, où une forme singulière est généralement acceptée? Déjà vu, déjà fait - réutilisons.

Problème de nommage de table : Noms singuliers vs. pluriels

Answer 5

Alors que la pratique la plus répandue est l'utilisation d'API RESTful où les pluriels sont utilisés par exemple /api/resources/123, il y a un cas particulier où j'estime qu'un nom singulier est plus approprié/expressif que des noms au pluriel. Il s'agit des relations un à un. Plus précisément, si l'élément cible est un objet de valeur (dans le paradigme de la conception pilotée par le domaine).

Supposons que chaque ressource ait un accessLog un à un qui pourrait être modélisé comme un objet de valeur, c'est-à-dire non une entité donc pas d'ID. Cela pourrait être exprimé comme /api/resources/123/accessLog. Les verbes habituels (POST, PUT, DELETE, GET) exprimeraient de manière appropriée l'intention et aussi le fait que la relation est effectivement un à un.