Quand utiliser @QueryParam ou @PathParam ?

Question

Je ne pose pas la question qui est déjà posée ici : Quelle est la différence entre @PathParam et @QueryParam ?

Il s'agit d'une question de "meilleures pratiques" ou de convention.

Quand utiliseriez-vous @PathParam vs @QueryParam .

Ce que je peux penser, c'est que la décision pourrait utiliser les deux pour différencier le modèle d'information. Permettez-moi d'illustrer ci-dessous mon LTPO - less than perfect observation.

L'utilisation de PathParam pourrait être réservée à la catégorie d'information, qui s'inscrirait parfaitement dans une branche d'un arbre d'information. PathParam pourrait être utilisé pour descendre dans la hiérarchie des classes d'entités.

Alors que QueryParam pourrait être réservé à la spécification d'attributs pour localiser l'instance d'une classe.

Par exemple,

• /Vehicle/Car?registration=123
• /House/Colonial?region=newengland

/category?instance

@GET
@Path("/employee/{dept}")
Patient getEmployee(@PathParam("dept")Long dept, @QueryParam("id")Long id) ;

vs /category/instance

@GET
@Path("/employee/{dept}/{id}")
Patient getEmployee(@PathParam("dept")Long dept, @PathParam("id")Long id) ;

vs ?category+instance

@GET
@Path("/employee")
Patient getEmployee(@QueryParam("dept")Long dept, @QueryParam("id")Long id) ;

Je ne pense pas qu'il y ait une convention standard pour le faire. Y en a-t-il une ? Cependant, j'aimerais savoir comment les gens utilisent PathParam vs QueryParam pour différencier leurs informations comme je l'ai illustré ci-dessus. J'aimerais également connaître la raison de cette pratique.

Answer 1

REST n'est peut-être pas une norme en tant que telle, mais la lecture de la documentation générale sur REST et des articles de blog devrait vous donner des indications sur la manière de structurer les URL des API. La plupart des API de repos ont tendance à n'avoir que des noms de ressources et des ID de ressources dans le chemin. Par exemple :

/departments/{dept}/employees/{id}

Certaines API REST utilisent des chaînes de requête pour le filtrage, la pagination et le tri, mais comme REST n'est pas une norme stricte, je vous recommande de consulter certaines API REST telles que github y stackoverflow et voyez ce qui pourrait convenir à votre cas d'utilisation.

Je recommanderais de mettre tous les paramètres obligatoires dans le chemin d'accès, et tous les paramètres facultatifs devraient certainement être des paramètres de chaîne de requête. Si vous mettez des paramètres facultatifs dans le chemin d'accès, vous risquez de vous retrouver dans une situation très compliquée si vous essayez d'écrire des gestionnaires d'URL qui correspondent à différentes combinaisons.

Answer 2

C'est ce que je fais.

S'il y a un scénario pour récupérer un enregistrement basé sur l'id, par exemple vous avez besoin d'obtenir les détails de l'employé dont l'id est 15, alors vous pouvez avoir une ressource avec @PathParam.

GET /employee/{id}

Si vous avez besoin d'obtenir les détails de tous les employés, mais seulement 10 à la fois, vous pouvez utiliser le paramètre de la requête.

GET /employee?start=1&size=10

Cela signifie qu'en commençant par l'employé ID 1, on obtient dix enregistrements.

Pour résumer, utilisez @PathParam pour la récupération basée sur l'id. Utilisez @QueryParam pour le filtre ou si vous avez une liste fixe d'options que l'utilisateur peut passer.

Answer 3

Je pense que si le paramètre identifie une entité spécifique, vous devriez utiliser une variable de chemin. Par exemple, pour obtenir tous les articles de mon blog, je demande

GET: myserver.com/myblog/posts

pour obtenir le message avec id = 123, je demanderais

GET: myserver.com/myblog/posts/123

mais pour filtrer ma liste de messages, et obtenir tous les messages depuis le 1er janvier 2013, je demanderais

GET: myserver.com/myblog/posts?since=2013-01-01

Dans le premier exemple, "posts" identifie une entité spécifique (la collection entière de billets de blog). Dans le deuxième exemple, "123" représente également une entité spécifique (un seul billet de blog). Mais dans le dernier exemple, le paramètre "since=2013-01-01" est une demande de filtrage de la collection de billets et non une entité spécifique. La pagination et l'ordonnancement seraient un autre bon exemple, à savoir

GET: myserver.com/myblog/posts?page=2&order=backward

J'espère que cela vous aidera. :-)

Answer 4

Personnellement, j'ai utilisé l'approche suivante : "si l'utilisateur a intérêt à marquer d'un signet une URL qui comprend ces paramètres, alors utilisez PathParam".

Par exemple, si l'URL d'un profil d'utilisateur comprend un paramètre d'identifiant de profil, étant donné que celui-ci peut être ajouté à un signet par l'utilisateur et/ou envoyé par e-mail, j'inclurais cet identifiant de profil comme paramètre de chemin. Un autre avantage est que la page désignée par l'URL qui inclut le paramètre de chemin d'accès ne change pas - l'utilisateur configure son profil, l'enregistre et il est peu probable qu'il change beaucoup à partir de là ; cela signifie que les robots d'exploration, les moteurs de recherche, les navigateurs, etc. peuvent mettre cette page en cache en se basant sur le chemin d'accès.

Si un paramètre passé dans l'URL est susceptible de modifier la présentation ou le contenu de la page, je l'utiliserais comme paramètre de requête. Par exemple, si l'URL du profil prend en charge un paramètre qui spécifie si l'e-mail de l'utilisateur doit être affiché ou non, je le considérerais comme un paramètre de requête. (Je sais que, sans doute, on pourrait dire que l'option &noemail=1 ou tout autre paramètre peut être utilisé comme paramètre de chemin et générer 2 pages distinctes -- une avec l'email, une sans -- mais logiquement ce n'est pas le cas : c'est toujours la même page avec ou sans certains attributs affichés.

J'espère que cela vous aidera - j'apprécie que l'explication puisse être un peu floue :)

Answer 5

Vous pouvez utiliser des paramètres de requête pour le filtrage et des paramètres de chemin pour le regroupement. Le lien suivant contient de bonnes informations à ce sujet Quand utiliser pathParams ou QueryParams ?