Conventions de dénomination des API reposantes
Donc, mon patron et moi ne sommes pas d'accord ici et ne pouvons trouver aucune information à ce sujet. Scénario: je souhaite obtenir tous les utilisateurs d'une organisation donnée. Quelle devrait être l'URL?
mydomain.com/users/by/organisation/{orgId}
OR
mydomain.com/organisation/{orgId}/users
Nos arguments:
Cas 1: l’appel doit renvoyer des "utilisateurs" et la "ressource" (première partie de l’appel) doit donc s'y rapporter.
Cas 2: L'organisation "possède"/"est le parent de" l'utilisateur et par conséquent, l'organisation doit être la première.
Quelles sont vos pensées?
UPDATE: Je ne dois pas m'inquiéter de ce qui vient après le mydomain.com/{resource}. La question porte principalement sur le point de savoir si l'action HTTP (GET, POST, PUT, DELETE) doit concerner la première ressource mydomain.com/users ou si elle doit refléter la relation mydomain.com/organisations/users/.
Vous savez probablement que REST n'a pas de règles strictes, vous êtes plus ou moins libre de l'implémenter comme bon vous semble, mais voici mes 2 centimes
mydomain.com/users/by/organisation/{orgId}
Cependant, cela ressemble à une bonne URL, car il vous dit ce qu’il fait en le lisant, ce n’est pas une bonne idée. Normalement, chaque segment d’URL spécifie une ressource qui existe ou peut exister.
Dans ce cas, users représente une ou plusieurs ressources, de même que organisation, mais by ne le fait pas. Ce n'est probablement qu'un mot pour aider à clarifier le rôle de l'API.
L'appel est censé renvoyer des "utilisateurs" et la "ressource" (première partie de l'appel) doit donc s'y rapporter.
Une ressource n'est pas nécessairement spécifiée dans la première partie de l'URL. Cela peut être le 2ème, 3ème ou 10ème si vous voulez
mydomain.com/organisation/{orgId}/users
Cela a l'air beaucoup mieux, mais je pense qu'il y a 1 point d'amélioration. Vous devez renommer organisation en organisations, afin de correspondre à users
Ce
mydomain.com/organisations/{orgId}
puis obtient l'organisation avec l'ID orgId, et
mydomain.com/organisations/{orgId}/users
obtient tous les utilisateurs qui appartiennent à cette organisation.
Pour le réduire, vous pouvez le faire
mydomain.com/organisations/{orgId}/users/{userId}
obtenir un utilisateur spécifique appartenant à une organisation spécifique
MISE À JOUR: Je ne m'inquiète pas de ce qui vient après Mydomain.com/{resource}. La question porte principalement sur le point de savoir si l'action [ Action HTTP (GET, POST, PUT, DELETE) doit concerner la première ressource mydomain.com/users ou si elle doit refléter la relation mydomain.com/organisations/users/.
Pour répondre à votre mise à jour:
Je l'ai déjà mentionné ci-dessus; Une ressource n'est pas nécessairement spécifiée dans la première partie de l'URL. . Si la qualité de l'URL s'améliore en déplaçant la ressource recherchée à l'arrière de l'URL, continuez ainsi.
Laissez-moi commencer par ceci: techniquement, cela ne devrait pas vraiment avoir REST indique que les URL doivent pouvoir être découvertes via des liens, comme des liens dans des pages Web normales (HTML).
Cependant, une structure d'URL cohérente et explicite ne nuira pas du tout. Je suggérerais une structure hiérarchique dans les URL:
/organisationsrenvoie une liste de toutes les organisations/organisations/123renvoie une organisation spécifique (# 123)/organisations/123/usersrenvoie une liste d'utilisateurs associés à cette organisation- etc.
Une alternative serait d'utiliser une chaîne de requête pour filtrer:
/usersrenvoie une liste de tous les utilisateurs/users?organisation=123renvoie une liste d'utilisateurs associés à cette organisation
De ce point de vue hiérarchique, /users/by/organisation/123 n'aurait pas beaucoup de sens. Quel serait le résultat d'appeler /users/by/organisation? Ou /users/by?
Il existe une différence conceptuelle entre ce que vous essayez de montrer ici. Le premier est un filtrage de toutes les ressources utilisateur du système en fonction de certains critères. La seconde montre les ressources utilisateur appartenant à une organisation.
La deuxième URL est correcte pour montrer aux utilisateurs appartenant à une organisation, je pense.
La première URL filtre effectivement les utilisateurs que vous voulez voir de tous les utilisateurs.
L'utilisation de l'URL peut convenir au filtrage, bien que l'utilisation de la chaîne de requête url le soit également. alors
mydomain.com/users?organisationId={orgId}
pourrait être préférable. Les URL peuvent toujours contenir des chaînes de requête et être reposantes.
Est-ce vraiment logique de DELETE mydomain.com/users/organisation/{orgid}? Vous attendriez-vous à ce que cela supprime l'organisation? Si ce n'est pas le cas, cela ne pointe pas vraiment sur une ressource et vous faites donc une recherche, et vous devriez probablement utiliser des chaînes de requête.
Il existe d'autres options pour effectuer la recherche, telles que faire des critères de recherche un objet de première classe ou utiliser l'une des autres techniques de filtrage dans cette question ou cette question
mydomain.com/users/by/organisation/{orgId}
Que veut dire "par"? Cela n'a aucun rapport avec quoi que ce soit. Essayez de conservez des mots aléatoires en dehors de l’URL .
Cas 1: l’appel doit renvoyer des "utilisateurs" et la "ressource" (première partie de l’appel) doit donc s'y rapporter.
Ce n'est pas une règle que les API RESTful appliquent ou attendent. Ce n’est vraiment pas courant dans l’industrie non plus, et j’ai travaillé avec une foule d’API. Considérez cela comme un dossier.
- / users - une liste d'utilisateurs
- / users/1 - utilisateur avec un ID de 1
- / users/1/organisations - les organisations auxquelles cet utilisateur appartient
- / organisations - une liste d'organisations
- / organisations/1 - numéro d'organisation 1
- / organisations/1/utilisateurs - Les utilisateurs de cette organisation
Vous le regardez comme un programmeur, comme s'il s'agissait de SOAP ou d'une fonction PHP, essayant de créer getUsersByOrganization($orgId) et ce n'est pas ainsi que fonctionne REST. :)
SI vous devez vous en tenir au cas 1 (premier segment d'URI = type de retour), procédez comme suit:
- / utilisateurs? orgId = 1
C'est parfaitement RESTful et c'est essentiellement juste un filtre. Vous pouvez même faire les deux, mais pas moi. C'est une relation qui n'a pas sa place là-bas. J'essaie de garder des filtres sur des choses comme:? Active = true
Par REST, la structure d'URI n'a d'importance que du point de vue humain. Cela n'a pas d'importance du point de vue du client REST, car il s'agit d'un lien annoté avec une sémantique.
Pour répondre à votre question, peu importe ce que vous voulez décrire, les relations ou les utilisateurs. Si vous souhaitez ajouter et supprimer des relations, vous devez définir une collection de relations. Si vous souhaitez ajouter et supprimer des utilisateurs, vous devez définir un groupe d'utilisateurs. Cela ne compte que par manipulation. Par GET, vous pouvez définir n’importe quel type de requête qui renvoie un groupe d’utilisateurs ...
La seconde est meilleure. En descendant l'URI, la requête doit être réduite, soit en tant que filtres, soit en affichant des objets parent-enfant. Les utilisateurs appartiennent à une organisation, il devrait donc s'agir d'une organisation/d'utilisateurs. Mais je supprimerais aussi le niveau "organisation" de l'URI si possible.
mydomain.com/{orgId}/users