Convention REST URI - Nom singulier ou pluriel de la ressource lors de sa création

Je suis nouveau sur REST et j'ai observé que dans certains services RESTful, ils utilisent différentes URI de ressources pour la mise à jour / obtenir / supprimer et créer. Tel que

• Créer - en utilisant / resources avec la méthode POST (observez le pluriel) à certains endroits en utilisant / resource (singulier)
• Mise à jour - utilisation de / resource / 123 avec la méthode PUT
• Get - Utilisation de / resource / 123 avec la méthode GET

Je suis un peu confus au sujet de cette convention de dénomination d'URI. Que devons-nous utiliser au pluriel ou au singulier pour la création de ressources? Quels devraient être les critères pour décider de cela?

La prémisse de l'utilisation /resourcesest qu'elle représente "toutes" les ressources. Si vous le faites GET /resources, vous retournerez probablement la collection entière. En POSTANT sur /resources, vous ajoutez à la collection.

Cependant, les ressources individuelles sont disponibles dans / ressource. Si vous faites cela GET /resource, vous allez probablement faire une erreur, car cette demande n'a aucun sens, alors qu'elle /resource/123est parfaitement logique.

En utilisant au /resourcelieu de /resourcesest similaire à la façon dont vous le feriez si vous travaillez avec, par exemple, un système de fichiers et une collection de fichiers et /resourceest le « répertoire » avec l'individu 123, les 456fichiers qu'il contient .

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

Pour moi, il vaut mieux avoir un schéma que vous pouvez mapper directement au code (facile à automatiser), principalement parce que le code sera ce qui va se passer 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) 

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

Pluriel

• Simple - toutes les URL commencent par le même préfixe
• Logique - orders/obtient une liste d'index des commandes.
• Norme - Norme la plus largement adoptée, suivie par l'écrasante majorité des API publiques et privées.

Par exemple:

GET /resources - retourne une liste des éléments de ressource

POST /resources - crée un ou plusieurs éléments de ressource

PUT /resources - met à jour un ou plusieurs éléments de ressource

PATCH /resources - met à jour partiellement un ou plusieurs éléments de ressource

DELETE /resources - supprime tous les éléments de ressource

Et pour les éléments de ressource unique:

GET /resources/:id- renvoie un élément de ressource spécifique basé sur un :idparamètre

POST /resources/:id - crée un élément de ressource avec l'ID spécifié (nécessite une validation)

PUT /resources/:id - met à jour un élément de ressource spécifique

PATCH /resources/:id - met à jour partiellement un élément de ressource spécifique

DELETE /resources/:id - supprime un élément de ressource spécifique

Aux défenseurs du singulier, pensez-y de cette façon: demanderiez-vous à quelqu'un orderune chose et attendez-vous une chose ou une liste de choses? Alors, pourquoi vous attendriez-vous à ce qu'un service retourne une liste de choses lorsque vous tapez /order?

Singulier

Commodité choses peuvent avoir des noms pluriels irréguliers. Parfois, ils n'en ont pas. Mais les noms singuliers sont toujours là.

par exemple CustomerAddress sur CustomerAddresses

Considérez cette ressource connexe.

C'est /order/12/orderdetail/12plus lisible et logique que/orders/12/orderdetails/4 .

Tables de base de données

Une ressource représente une entité comme une table de base de données. Il doit avoir un nom singulier logique. Voici la réponse sur les noms de table.

Cartographie des classes

Les cours sont toujours singuliers. Les outils ORM génèrent des tables avec les mêmes noms que les noms de classe. Comme de plus en plus d'outils sont utilisés, les noms singuliers deviennent une norme.

En savoir plus sur le dilemme d'un développeur d'API REST

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

Supposons que chaque ressource possède un un à un accessLogqui pourrait être modélisé comme un objet de valeur, c'est -à- dire pas une entité, donc pas d'ID. Il pourrait être exprimé comme suit /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 en effet un à un.

Pourquoi ne pas suivre la tendance répandue des noms de table de base de données, où une forme singulière est généralement acceptée? J'y suis allé, j'ai fait ça - réutilisons.

Dilemme de nom de table: noms singuliers ou pluriels

Je suis surpris de voir que tant de gens sautent dans le train du nom pluriel. Lors de la mise en œuvre de conversions du singulier au pluriel, vous occupez-vous des noms pluriels irréguliers? Aimez-vous la douleur?

Voir http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Il existe de nombreux types de pluriel irrégulier, mais ce sont les plus courants:

Type de nom Former le pluriel Exemple

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

Du point de vue du consommateur d'API, les points de terminaison doivent être prévisibles afin

Idéalement...

1. GET /resources devrait renvoyer une liste de ressources.
2. GET /resource doit renvoyer un code d'état de 400 niveaux.
3. GET /resources/id/{resourceId} devrait renvoyer une collection avec une ressource.
4. GET /resource/id/{resourceId} devrait renvoyer un objet ressource.
5. POST /resources devrait créer des ressources par lots.
6. POST /resource devrait créer une ressource.
7. PUT /resource devrait mettre à jour un objet ressource.
8. PATCH /resource doit mettre à jour une ressource en affichant uniquement les attributs modifiés.
9. PATCH /resources devrait mettre à jour les ressources par lots affichant uniquement les attributs modifiés.
10. DELETE /resourcesdevrait supprimer toutes les ressources; je plaisante: 400 code de statut
11. DELETE /resource/id/{resourceId}

Cette approche est la plus flexible et la plus riche en fonctionnalités, mais aussi la plus longue à développer. Donc, si vous êtes pressé (ce qui est toujours le cas avec le développement de logiciels), nommez simplement votre point de terminaison resourceou le pluriel resources. Je préfère la forme singulière car elle vous donne la possibilité d'introspection et d'évaluation par programme car toutes les formes plurielles ne se terminent pas par 's'.

Cela dit, pour une raison quelconque, le développeur de pratique le plus couramment choisi a choisi d'utiliser le pluriel. C'est finalement la voie que j'ai choisie et si vous regardez les API populaires comme githubet twitter, c'est ce qu'elles font.

Certains critères de décision pourraient être:

1. Quelles sont mes contraintes de temps?
2. Quelles opérations vais-je permettre à mes consommateurs de faire?
3. À quoi ressemblent la demande et la charge utile résultante?
4. Est-ce que je veux pouvoir utiliser la réflexion et analyser l'URI dans mon code?

C'est à vous de répondre. Quoi que vous fassiez, soyez cohérent.

Mes deux cents: les méthodes qui passent leur temps à passer du pluriel au singulier ou vice-versa sont une perte de cycles CPU. Je suis peut-être de la vieille école, mais à mon époque, les choses s'appelaient pareil. Comment rechercher des méthodes concernant des personnes? Aucune expression régulière ne couvrira à la fois la personne et les personnes sans effets secondaires indésirables.

Les pluriels anglais peuvent être très arbitraires et ils encombrent inutilement le code. Respectez une seule convention de dénomination. Les langages informatiques étaient censés concerner la clarté mathématique, et non l'imitation du langage naturel.

Je préfère utiliser la forme singulière pour la simplicité et la cohérence.

Par exemple, en considérant l'URL suivante:

/ client / 1

Je traiterai le client comme une collection client, mais pour simplifier, la partie collection est supprimée.

Un autre exemple:

/ équipement / 1

Dans ce cas, les équipements ne sont pas la forme plurielle correcte. Le traiter comme une collection d'équipements et le supprimer pour plus de simplicité le rend cohérent avec le cas client.

Un identifiant dans un itinéraire doit être vu de la même manière qu'un index d'une liste, et la dénomination doit procéder en conséquence.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

Mais certaines ressources n'utilisent pas d'identifiants dans leurs itinéraires car il n'y en a qu'un ou un utilisateur n'a jamais accès à plusieurs, donc ce ne sont pas des listes:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

Avec les conventions de dénomination, il est généralement prudent de dire «choisissez-en un et respectez-le», ce qui est logique.

Cependant, après avoir expliqué REST à de nombreuses personnes, représenter les points de terminaison comme des chemins sur un système de fichiers est le moyen le plus expressif de le faire.
Il est sans état (les fichiers existent ou n'existent pas), hiérarchique, simple et familier - vous savez déjà comment accéder aux fichiers statiques, que ce soit localement ou via http.

Et dans ce contexte, les règles linguistiques ne peuvent vous mener que dans la mesure suivante:

Un répertoire peut contenir plusieurs fichiers et / ou sous-répertoires, et son nom doit donc être au pluriel.

Et j'aime ça.
Bien que, d'un autre côté - c'est votre répertoire, vous pouvez le nommer "une-ressource-ou-plusieurs-ressources" si c'est ce que vous voulez. Ce n'est pas vraiment la chose importante.

Ce qui est important, c'est que si vous placez un fichier nommé "123" dans un répertoire nommé "resourceS" (résultant en /resourceS/123), vous ne pouvez pas vous attendre à ce qu'il soit accessible via/resource/123 .

N'essayez pas de le rendre plus intelligent qu'il ne doit l'être - passer du pluriel au singluar en fonction du nombre de ressources auxquelles vous accédez actuellement peut être esthétique pour certains, mais ce n'est pas efficace et cela n'a pas de sens dans un système hiérarchique .

Remarque: Techniquement, vous pouvez créer des "liens symboliques", ce qui /resources/123est également accessible via /resource/123, mais le premier doit encore exister!

Jetez un oeil à Google d » API Guide de conception: les noms des ressources pour une autre prise sur les ressources de nommage.

En bref:

• Les collections sont nommées avec des pluriels.
• Les ressources individuelles sont nommées avec une chaîne.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /[email protected] | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

Cela vaut la peine d'être lu si vous pensez à ce sujet.

L'utilisation du pluriel pour toutes les méthodes est plus pratique au moins sous un aspect: si vous développez et testez une API de ressource à l'aide de Postman (ou d'un outil similaire), vous n'avez pas besoin de modifier l'URI lorsque vous passez de GET à PUT à POST, etc. .

Les deux représentations sont utiles. J'avais utilisé le singulier pour plus de commodité pendant un certain temps, l'inflexion peut être difficile. Mon expérience dans le développement d'API REST strictement singulières, les développeurs consommant le point de terminaison manquant de certitude quant à la forme du résultat. Je préfère maintenant utiliser le terme qui décrit le mieux la forme de la réponse.

Si toutes vos ressources sont de niveau supérieur, vous pouvez vous en sortir avec des représentations singulières. Éviter l'inflexion est une grande victoire.

Si vous effectuez une sorte de lien profond pour représenter des requêtes sur les relations, les développeurs écrivant sur votre API peuvent être aidés par une convention plus stricte.

Ma convention est que chaque niveau de profondeur dans un URI décrit une interaction avec la ressource parent, et l'URI complet devrait décrire implicitement ce qui est récupéré.

Supposons que nous ayons le modèle suivant.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Si je devais fournir une ressource qui permet à un client d'obtenir le gestionnaire d'un ami particulier d'un utilisateur particulier, cela pourrait ressembler à ceci:

GET /users/{id}/friends/{friendId}/manager

Voici quelques exemples supplémentaires:

• GET /users - répertorier les ressources utilisateur dans la collection d'utilisateurs globale
• POST /users - créer un nouvel utilisateur dans la collection globale d'utilisateurs
• GET /users/{id} - récupérer un utilisateur spécifique de la collection d'utilisateurs globale
• GET /users/{id}/manager - obtenir le gestionnaire d'un utilisateur spécifique
• GET /users/{id}/friends - obtenir la liste des amis d'un utilisateur
• GET /users/{id}/friends/{friendId} - obtenir un ami spécifique d'un utilisateur
• LINK /users/{id}/friends - ajouter une association d'amis à cet utilisateur
• UNLINK /users/{id}/friends - supprimer une association d'amis de cet utilisateur

Remarquez comment chaque niveau correspond à un parent sur lequel il est possible d'agir. L'utilisation de parents différents pour le même objet est contre-intuitive. La récupération d'une ressource à GET /resource/123ne laisse aucune indication que la création d'une nouvelle ressource doit être effectuée àPOST /resources

Je sais que la plupart des gens sont entre décider d'utiliser le pluriel ou le singulier. Le problème qui n'a pas été abordé ici est que le client devra savoir lequel vous utilisez, et il est toujours probable qu'il fasse une erreur. C'est de là que vient ma suggestion.

Et les deux? Et par cela, je veux dire utiliser le singulier pour l'ensemble de votre API, puis créer des itinéraires pour transmettre les demandes faites au pluriel au singulier. Par exemple:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Vous obtenez l'image. Personne n'a tort, un effort minimal et le client aura toujours raison.

Je n'aime pas voir la {id}partie des URL se chevaucher avec des sous-ressources, car cela idpourrait théoriquement être n'importe quoi et il y aurait une ambiguïté. Il mélange différents concepts (identifiants et noms de sous-ressources).

Des problèmes similaires sont souvent vus dans des enumconstantes ou dossier structures, où les différents concepts sont mélangés (par exemple, lorsque vous avez des dossiers Tigers, Lionset Cheetahs, puis aussi un dossier appelé Animalsau même niveau - cela n'a aucun sens que l' on est un sous - ensemble de la autre).

En général, je pense que la dernière partie nommée d'un point de terminaison devrait être singulière si elle concerne une seule entité à la fois, et plurielle si elle traite d'une liste d'entités.

Donc, les points de terminaison qui traitent avec un seul utilisateur:

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

Ensuite, il existe une ressource distincte pour effectuer des requêtes sur les utilisateurs, qui retournent généralement une liste:

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

Et voici quelques exemples d'une sous-ressource qui traite avec un utilisateur spécifique:

GET /user/{id}/friends -> Returns a list of friends of given user

Faites-vous un ami (lien plusieurs à plusieurs):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

Il n'y a jamais d'ambiguïté, et la dénomination plurielle ou singulière de la ressource est une indication pour l'utilisateur de ce à quoi il peut s'attendre (liste ou objet). Il n'y a pas de restrictions sur ids, ce qui permet théoriquement d'avoir un utilisateur avec l'id newsans chevaucher avec un nom de sous-ressource (futur potentiel).

Utilisez le singulier et profitez de la convention anglaise vue par exemple dans "Business Directory".

Beaucoup de choses lisent de cette façon: "Book Book", "Dog Pack", "Art Gallery", "Film Festival", "Car Lot", etc.

Cela correspond commodément au chemin de l'URL de gauche à droite. Type d'élément à gauche. Définissez le type à droite.

Récupère-t-il GET /usersvraiment un ensemble d'utilisateurs? Pas habituellement. Il récupère un ensemble de talons contenant une clé et peut-être un nom d'utilisateur. Ce n'est donc pas vraiment de /userstoute façon. C'est un index d'utilisateurs, ou un "index d'utilisateurs" si vous voulez. Pourquoi ne pas l'appeler ainsi? C'est un /user/index. Puisque nous avons nommé le type d'ensemble, nous pouvons avoir plusieurs types montrant différentes projections d'un utilisateur sans avoir recours aux paramètres de requête, par exemple user/phone-listou /user/mailing-list.

Et qu'en est-il de l'utilisateur 300? C'est encore /user/300.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

En conclusion, HTTP ne peut avoir qu'une seule réponse à une seule demande. Un chemin fait toujours référence à quelque chose de singulier.

Pour moi, les pluriels manipulent la collection , tandis que les singuliers manipulent l' élément à l' intérieur de cette collection.

La collecte permet les méthodes GET / POST / DELETE

L'élément permet les méthodes GET / PUT / DELETE

Par exemple

POST sur / les étudiants ajouteront un nouvel étudiant à l'école.

SUPPRIMER sur / élèves supprimera tous les élèves de l'école.

SUPPRIMER sur / étudiant / 123 supprimera l'élève 123 de l'école.

Cela peut sembler sans importance, mais certains ingénieurs oublient parfois l'ID. Si l'itinéraire était toujours pluriel et effectuait une SUPPRESSION, vous pourriez accidentellement effacer vos données. Alors que manquer l'identifiant au singulier renverra une route 404 introuvable.

Pour développer davantage l'exemple si l'API était censée exposer plusieurs écoles, alors quelque chose comme

SUPPRIMER dans / école / abc / élèves supprimera tous les élèves de l'école abc.

Choisir le bon mot est parfois un défi en soi, mais j'aime maintenir la pluralité pour la collection. Par exemple cart_itemsou cart/itemsse sent bien. En revanche, la suppression cartsupprime l'objet du panier lui-même et non les articles du panier;).

Que diriez-vous:

/resource/(pas /resource)

/resource/ signifie que c'est un dossier contenant quelque chose appelé "ressource", c'est un dossier "resouce".

Et je pense aussi que la convention de dénomination des tables de base de données est la même, par exemple, une table appelée "utilisateur" est une "table utilisateur", elle contient quelque chose appelé "utilisateur".

Je préfère utiliser les deux au pluriel (/resources ) et le singulier ( /resource/{id}) car je pense que cela sépare plus clairement la logique entre travailler sur la collecte de ressources et travailler sur une seule ressource.

En tant qu'effet secondaire important, cela peut également aider à empêcher quelqu'un d'utiliser incorrectement l'API. Par exemple, considérons le cas où un utilisateur essaie à tort d'obtenir une ressource en spécifiant l'ID en tant que paramètre comme ceci:

GET /resources?Id=123

Dans ce cas, lorsque nous utilisons la version plurielle, le serveur ignorera très probablement le paramètre Id et renverra la liste de toutes les ressources. Si l'utilisateur ne fait pas attention, il pensera que l'appel a réussi et utilisera la première ressource de la liste.

En revanche, lors de l'utilisation du singulier:

GET /resource?Id=123

le serveur retournera très probablement une erreur parce que l'ID n'est pas spécifié de la bonne manière, et l'utilisateur devra se rendre compte que quelque chose ne va pas.