Meilleures pratiques de l'API REST: arguments dans la chaîne de requête vs dans le corps de la requête

Une API REST peut avoir des arguments à plusieurs endroits:

1. Dans le corps de la requête - Dans le cadre d'un corps json ou d'un autre type MIME
2. Dans la chaîne de requête - par exemple/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 pour choisir entre 1 et 2 ci-dessus?
2 vs 3 est couvert ici .

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

Habituellement, le corps du contenu est utilisé pour les données à charger / télécharger vers / depuis le serveur et les paramètres de requête sont utilisés pour 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 récupérez la liste de fichiers, vous pouvez utiliser les paramètres de requête pour filtrer la liste par une propriété des fichiers. En général, les paramètres de la 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 la mettre en œuvre de la manière qui vous convient le mieux / qui fonctionne pour vous.

Vous pouvez également consulter l' article de wikipedia sur la chaîne de requête , en particulier les deux premiers paragraphes.

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

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

Vous avez demandé une meilleure pratique, la sémantique suivante est la mienne. Bien sûr, l'utilisation de vos règles empiriques devrait fonctionner, en particulier si le framework Web que vous utilisez résume cela en paramètres .

Vous le savez 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 requête avec CURL.
• L'endroit où vous envoyez les données ne devrait pas avoir d'effet sur le débogage.

Voici 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
• Lorsque vous avez un très grand nombre d'arguments

Quand utiliser la chaîne de requête:

• Lorsque les arguments sont tels que vous souhaitez les voir lors du débogage
• Lorsque vous souhaitez pouvoir les appeler manuellement tout en développant le code, par exemple 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 plus communs, ceux qui devraient être déboguables dans la chaîne de requête, et jetez tout le reste dans le json.