348 votes

et où il doit mettre la bouteille.

Une API REST peuvent avoir des paramètres de deux façons au moins:

  1. Dans le cadre de la chemin de l'URL (c'est à dire /api/resource/parametervalue )
  2. Comme une requête argument (c - /api/resource?parameter=value )

Quelle est la meilleure pratique ici? Existe-il des lignes directrices générales lors de l'utilisation de 1 à 2?

L'exemple du monde réel: Twitter utilise des paramètres de requête pour spécifier des intervalles. (http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

Serait-il être considéré comme la meilleure conception pour mettre ces paramètres dans le chemin de l'URL?

254voto

Darrel Miller Points 56797

Si il y a des meilleures pratiques documentées, je n'ai pas encore trouvés. Cependant, ici sont quelques lignes directrices-je utiliser pour déterminer où placer les paramètres dans une url:

Les paramètres facultatifs ont tendance à être plus facile à mettre dans la chaîne de requête.

Si vous voulez retourner une erreur 404 lorsque la valeur de paramètre ne correspond pas à une ressource existante alors j'aurais tendance vers un segment de chemin de paramètre. par exemple, /customer/232 où 232 n'est pas valide id de client.

Toutefois, si vous souhaitez renvoyer une liste vide, puis lorsque le paramètre n'est pas trouvé, alors je vous suggérons d'utiliser des paramètres de chaîne de requête. par exemple, /contacts?name=dave

Si un paramètre affecte l'ensemble d'une sous-arborescence de votre espace d'URI, puis utiliser un segment de chemin. par exemple, un paramètre de langue /en/document/foo.txt contre /document/foo.txt?language=en

Je préfère d'identificateurs uniques pour être dans un segment de chemin plutôt que d'un paramètre de requête.

Les règles officielles pour les Uri sont trouvés dans ce RFC spec ici. Il y a aussi un autre très utile RFC spec ici, qui définit des règles de paramétrage des URIs.

152voto

Tor Valamo Points 14209

Réponse tardive mais je vais ajouter une idée supplémentaire à ce qui a été partagé, à savoir qu'il existe plusieurs types de "paramètres" à une demande, et vous devriez prendre cela en compte.

  1. Les Locators - E. g. identificateurs de ressources telles que l'Id ou l'action/afficher
  2. Filtres - E. g. des paramètres qui donnent une recherche, de tri ou de restreindre le jeu de résultats.
  3. L'état - E. g. identification de la session, les clés api, whatevs.
  4. Contenu - E. g. le stockage de données.

Examinons maintenant les différents endroits où ces paramètres pourrait aller.

  1. En-têtes de requête et cookies
  2. Chaîne de requête URL ("GET" vars)
  3. Les chemins d'URL
  4. Corps de chaîne de requête/multipart ("POST" vars)

En général, vous voulez de l'État à définir dans les en-têtes ou les cookies, en fonction du type d'informations d'état il est. Je pense que nous pouvons tous être d'accord sur ce point. Utiliser les en-têtes http personnalisés (X-Ma-Tête), si vous en avez besoin.

De même, le Contenu n'a qu'un lieu d'appartenance, qui est dans le corps de la requête, soit en tant que chaînes de requête ou en http en plusieurs parties et/ou le contenu JSON. Ceci est cohérent avec ce que vous recevez à partir du serveur lors de l'envoi de votre contenu. Donc, vous ne devriez pas être impoli et le faire différemment.

Les Locators comme "id=5" ou "action=actualiser" ou "page=2" serait plus logique d'avoir l'adresse de l'URL, comme mysite.com/article/5/page=2 où en partie, vous savez ce que chaque partie est censée signifier (les principes de base tels que l'article et 5 signifie évidemment m'obtenir les données de type article avec l'id 5) et d'autres paramètres sont spécifiés en tant que partie de l'URI. Ils peuvent être sous la forme d' page=2ou page/2 si vous savez qu'après un certain point dans l'URI les "dossiers" sont jumelés valeurs-clés.

Les filtres de toujours aller dans la chaîne de requête, parce que pendant qu'ils sont une partie de la recherche de la droite de données, ils ne sont là que pour retourner un sous-ensemble ou de la modification de ce que les Localisateurs d'y retourner seul. La recherche en mysite.com/article/?query=Obama (sous-ensemble) est un filtre, et donc, est - /article/5?order=backwards (modification). Pensez à ce que cela ne, pas seulement ce qu'il a appelé!

Si la "vue" détermine le format de sortie, puis c'est un filtre (mysite.com/article/5?view=pdf) parce qu'elle renvoie à une modification d'une ressource, plutôt qu'en se focalisant sur les ressources que nous voulons. Si au lieu de cela, il décide de la partie spécifique de l'article, nous arrivons à voir (mysite.com/article/5/view=summary) alors c'est un localisateur.

Rappelez-vous, de circonscrire un ensemble de ressources est de filtrage. Localiser quelque chose de spécifique à l'intérieur d'une ressource est la localisation des... duh. Sous-ensemble de filtrage peut retourner n'importe quel nombre de résultats (même à 0). Localisation trouverez toujours cette instance spécifique de quelque chose (si elle existe). Modification de filtrage sera de retour les mêmes données que le locator, à l'exception modifié (si une telle modification n'est permise).

Espérons que cela a contribué à donner aux gens une certaine eureka moments s'ils ont été perdus sur où mettre les choses!

21voto

manuel aldana Points 4317

Il dépend de la structure. Il n'y a pas de règles pour les Uri au REPOS sur HTTP (chose principale est qu'ils sont uniques). Souvent il s'agit de la question du goût et de l'intuition...

Je prends approche suivante:

  • chemin d'accès d'url-élément: La ressource et de son chemin d'accès de l'élément forme une traversée de répertoire et un sous-ressource (par exemple, /articles/{id} , /users/articles). En cas de doute demandez à vos collègues s'ils pensent que la traversée et qu'ils pensent à "un autre répertoire" plus probable est l'élément le bon choix
  • paramètre de l'url: quand il n'y a pas de traversée de vraiment (ressources en matière de recherche avec plusieurs paramètres de requête sont un très bel exemple de cela)

18voto

PeterWong Points 10070

L’OMI les paramètres devraient être mieux comme arguments de la requête. L’url est utilisée pour identifier la ressource, alors que les paramètres de la requête Ajout pour spécifier quelle partie de la ressource que vous voulez, n’importe quel état la ressource devrait avoir, etc..

17voto

Satish Bellapu Points 435

La mise en œuvre reste,

1) variables de chemin d’accès sont utilisés pour l’action directe sur les ressources, comme un contact ou une chanson ex...
/Api/resource/songid GET etc. ou
/Api/resource/contactid GET etc. retournera des données respectives.

2) permanentes/argument de requête sont utilisés pour les ressources en direct comme les métadonnées d’une chanson ex.., GET /api/resource/songid ? métadonnées = genres il retourne les données de genres pour cette chanson en particulier.

Prograide.com

Prograide est une communauté de développeurs qui cherche à élargir la connaissance de la programmation au-delà de l'anglais.
Pour cela nous avons les plus grands doutes résolus en français et vous pouvez aussi poser vos propres questions ou résoudre celles des autres.

Powered by:

X