Je veux rendre mon API RESTful très prévisible. Quelle est la meilleure pratique pour décider quand effectuer une segmentation des données en utilisant l'URI plutôt qu'en utilisant des paramètres de requête.
Il est logique pour moi que les paramètres système qui prennent en charge la pagination, le tri et le regroupement soient après le «?» Mais qu'en est-il des champs tels que «statut» et «région» ou d'autres attributs qui segmentent votre collection? Si ceux-ci doivent également être des paramètres de requête, quelle est la règle de base pour savoir quand utiliser les paramètres de chemin?
Réponses:
La meilleure pratique pour la conception d'API RESTful est que les paramètres de chemin sont utilisés pour identifier une ou plusieurs ressources spécifiques, tandis que les paramètres de requête sont utilisés pour trier / filtrer ces ressources.
Voici un exemple. Supposons que vous implémentiez des points de terminaison d'API RESTful pour une entité appelée Car. Vous structureriez vos points de terminaison comme ceci:
GET
/cars
GET
/cars/:id
POST
/cars
PUT
/cars/:id
DELETE
/cars/:id
De cette façon, vous n'utilisez les paramètres de chemin que lorsque vous spécifiez la ressource à récupérer, mais cela ne trie / filtre en aucune façon les ressources.
Supposons maintenant que vous vouliez ajouter la possibilité de filtrer les voitures par couleur dans vos demandes GET. Étant donné que la couleur n'est pas une ressource (c'est une propriété d'une ressource), vous pouvez ajouter un paramètre de requête qui effectue cette opération. Vous ajouteriez ce paramètre de requête à votre requête GET
/cars
comme ceci:AVOIR
/cars?color=blue
Ce point de terminaison serait mis en œuvre de sorte que seules les voitures bleues soient renvoyées.
En ce qui concerne la syntaxe, vos noms d'URL doivent être tous en minuscules. Si vous avez un nom d'entité qui est généralement composé de deux mots en anglais, vous utiliseriez un trait d'union pour séparer les mots, pas la casse de chameau.
Ex.
/two-words
la source
La manière fondamentale de penser à ce sujet est la suivante:
Un URI est un identificateur de ressource qui identifie de manière unique une instance spécifique d'un TYPE de ressource. Comme tout le reste de la vie, chaque objet (qui est une instance d'un certain type) a un ensemble d'attributs qui sont soit invariants dans le temps, soit temporels.
Dans l'exemple ci-dessus, une voiture est un objet très tangible qui a des attributs comme la marque, le modèle et le NIV - qui ne change jamais, et la couleur, la suspension, etc. qui peuvent changer avec le temps. Donc, si nous encodons l'URI avec des attributs qui peuvent changer dans le temps (temporel), nous pouvons nous retrouver avec plusieurs URI pour le même objet:
Et des années plus tard, si la couleur de cette même voiture est changée en noir:
Notez que l'instance de voiture elle-même (l'objet) n'a pas changé - c'est juste la couleur qui a changé. Avoir plusieurs URI pointant vers la même instance d'objet vous obligera à créer plusieurs gestionnaires d'URI - ce n'est pas une conception efficace, et n'est bien sûr pas intuitive.
Par conséquent, l'URI ne doit être constitué que de parties qui ne changeront jamais et continueront à identifier de manière unique cette ressource tout au long de sa durée de vie. Tout ce qui peut changer doit être réservé aux paramètres de requête, en tant que tels:
En bout de ligne, pensez au polymorphisme.
la source
Dans une API REST, vous ne devriez pas être trop préoccupé par les URI prévisibles. La suggestion même de la prévisibilité des URI fait allusion à une incompréhension de l'architecture RESTful. Cela suppose qu'un client doit construire lui-même des URI, ce qu'il ne devrait vraiment pas avoir à faire.
Cependant, je suppose que vous ne créez pas une véritable API REST, mais une API `` inspirée de REST '' (comme celle de Google Drive). Dans ces cas, la règle d'or est «path params = resource identification» et «query params = resource sorting». Alors, la question devient, pouvez-vous identifier de manière unique votre ressource SANS statut / région? Si oui, alors c'est peut-être un paramètre de requête. Si non, alors c'est un paramètre de chemin.
HTH.
la source
Une fois, j'ai conçu une API qui était la ressource principale
people
. Habituellement, les utilisateurs demandaient filtré,people
donc, pour empêcher les utilisateurs d'appeler quelque chose comme à/people?settlement=urban
chaque fois, j'ai mis en œuvre/people/urban
ce qui m'a permis plus tard d'ajouter facilement/people/rural
. Cela permet également d'accéder à la/people
liste complète si elle serait utile plus tard. Bref, mon raisonnement était d'ajouter un chemin vers des sous-ensembles communsD' ici :
la source
De manière générale, j'ai tendance à utiliser des paramètres de chemin lorsqu'il existe une `` hiérarchie '' évidente dans la ressource, telle que:
Si cette seule ressource a un statut, on pourrait:
Cependant, si «région» ne fait pas vraiment partie de la ressource exposée, elle appartient probablement à l'un des paramètres de requête - similaire à la pagination (comme vous l'avez mentionné).
la source
La segmentation est plus hiérarchisée et "jolie" mais peut être limitative.
Par exemple, si vous avez une URL avec trois segments, chacun passant des paramètres différents pour rechercher une voiture via la marque, le modèle et la couleur:
C'est une très jolie URL et plus facilement mémorisable par l'utilisateur final, mais maintenant vous êtes coincé avec cette structure. Dites que vous voulez faire en sorte que dans la recherche, l'utilisateur puisse rechercher TOUTES les voitures bleues, ou TOUTES les Honda Civics? Un paramètre de requête résout ce problème car il donne une paire clé / valeur. Vous pourriez donc réussir:
Vous avez maintenant un moyen de référencer la valeur via sa clé - soit "color" ou "make" dans votre code de requête.
Vous pouvez contourner ce problème en utilisant éventuellement plus de segments pour créer une sorte de structure de valeur clé comme:
J'espère que cela a du sens.
la source
Exemple d'URL:
/rest/{keyword}
Cette URL est un exemple de paramètres de chemin. Nous pouvons obtenir ces données URL en utilisant
@PathParam
.Exemple d'URL:
/rest?keyword=java&limit=10
Cette URL est un exemple de paramètres de requête. Nous pouvons obtenir ces données URL en utilisant
@Queryparam
.la source