web-dev-qa-db-fra.com

REST Meilleures pratiques d'API: arguments dans la chaîne de requête et dans le corps de la demande

Une API REST peut avoir des arguments à plusieurs endroits:

  1. Dans le corps de la demande - En tant que partie d'un corps json ou d'un autre type MIME
  2. Dans le chaîne de requête - p. Ex. /api/resource?p1=v1&p2=v2
  3. Dans le cadre du chemin URL - par exemple. /api/resource/v1/v2

Quelles sont les meilleures pratiques et considérations à prendre en compte pour choisir entre 1 et 2 ci-dessus?
2 vs 3 est couvert ici .

jsonapiresthttpquery-string
74
Jonathan

Quelles sont les meilleures pratiques et considérations de choisir entre 1 et 2 ci-dessus?

Habituellement, le corps du contenu est utilisé pour les données à télécharger/à partir du serveur et les paramètres de requête permettent de spécifier les données exactes demandées. Par exemple, lorsque vous téléchargez un fichier, vous spécifiez le nom, le type MIME, etc. dans le corps, mais lorsque vous extrayez une liste de fichiers, vous pouvez utiliser les paramètres de requête pour filtrer la liste en fonction de la propriété des fichiers. En général, les paramètres de requête sont la propriété de la requête et non les données.

Bien sûr, ce n’est pas une règle stricte: vous pouvez l’appliquer de la manière qui vous semble la plus appropriée/qui fonctionne pour vous.

Vous pouvez également vouloir vérifier le article de Wikipédia sur la chaîne de requête , en particulier les deux premiers paragraphes.

23
stan0

Je suppose que vous parlez de requêtes POST/PUT. Sémantiquement, le corps de la demande doit contenir les données que vous publiez ou corrigez.

La chaîne de requête, dans le cadre de l'URL (un URI), sert à identifier la ressource que vous publiez ou corrigez.

Vous avez demandé les meilleures pratiques, la sémantique suivante est la mienne. Bien sûr, l'utilisation de vos règles empiriques devrait fonctionner, spécialement si le framework Web que vous utilisez est abstrait en paramètres.

Vous connaissez le plus:

  • Certains serveurs Web ont des limites sur la longueur de l'URI.
  • Vous pouvez envoyer des paramètres dans le corps de la demande avec CURL.
  • L'emplacement où vous envoyez les données ne devrait pas avoir d'effet sur le débogage.
11
Leonel Galán

Ce qui suit sont mes règles de base ...

Quand utiliser le corps:

  • Lorsque les arguments n'ont pas de clé plate: structure de valeur
  • Si les valeurs ne sont pas lisibles par l'homme, telles que les données binaires sérialisées
  • Quand vous avez un très grand nombre d'arguments

Quand utiliser la chaîne de requête:

  • Quand les arguments sont tels que vous voulez les voir pendant le débogage
  • Lorsque vous souhaitez pouvoir les appeler manuellement tout en développant le code, par ex. avec curl
  • Lorsque les arguments sont communs à de nombreux services Web
  • Lorsque vous envoyez déjà un type de contenu différent tel que application/octet-stream

Notez que vous pouvez mélanger et assortir - mettez les éléments communs, ceux qui doivent être débogables dans la chaîne de requête, et jetez tout le reste dans le JSON.

5
Jonathan