Rest Standard: paramètres de chemin ou Paramètres de requête

Tl; dr: vous pourriez vouloir les deux.

L'article # 42 existe:

GET /items/42
Accept: application/vnd.foo.item+json
--> 200 OK
{
    "id": 42,
    "bar": "baz"
}

GET /items?id=42
Accept: application/vnd.foo.item-list+json
--> 200 OK
[
    {
        "id": 42,
        "bar": "baz"
    }
]

L'article # 99 n'existe pas:

GET /items/99
Accept: application/vnd.foo.item+json
--> 404 Not Found

GET /items?id=99
Accept: application/vnd.foo.item-list+json
--> 200 OK
[
]

Explications et commentaires

1. /items/{id} renvoie un item tout /items?id={id} renvoie un item-list.
2. même s'il n'y a qu'un seul élément dans un item-list filtré, une liste d'un seul élément est toujours retournée pour la cohérence (par opposition à l'élément lui-même).
3. , Il se trouve que id est une propriété unique. Si nous étions à filtrer sur d'autres propriétés, cela fonctionnerait toujours exactement de la même manière.
4. les éléments d'une ressource de collection ne peuvent être nommés qu'à l'aide de propriétés uniques (par exemple, les clés en tant que sous-ressource de la collection) pour des raisons évidentes (ce sont des ressources normales et les URI identifient de manière unique les ressources).
5. Si l'élément n'est pas trouvé lors de l'utilisation d'un filtre, la réponse est toujours OK et contient toujours une liste (même vide). Juste parce que nous demandons une liste filtrée contenant un élément qui n'existe pas ne signifie pas que la liste elle-même n'existe pas.

Parce qu'ils sont si différents et indépendamment utiles, vous pourriez vouloir les deux . Le client voudra différencier tous les cas (par exemple si la liste est vide ou si la liste elle-même n'existe pas, auquel cas vous devriez renvoyer un 404 pour /items?...).

Avertissement: Cette approche est en aucun cas "standard". Cela a tellement de sens de moi bien que je me sentais comme partager.

PS: nommer la collection d'éléments " get " est une odeur de code; préférez "items" ou similaire.

Votre deuxième exemple de " paramètres de requête "n'est pas correct car" get " est inclus dans le chemin. GET est le type de requête, il ne devrait pas faire partie du chemin.

Il y a 4 types principaux de requêtes:

 GET
 PUT
 POST
 DELETE

Les requêtes GET doivent toujours pouvoir être complétées sans aucune information dans le corps de la requête. De plus, les requêtes GET doivent être "sûres", ce qui signifie qu'aucune donnée significative n'est modifiée par la requête.

Outre le problème de mise en cache mentionné ci-dessus, les paramètres du chemin D'URL auraient tendance à être requis et/ou attendus car ils font également partie de votre routage, alors que les paramètres passés dans la chaîne de requête sont plus variables et n'affectent pas la partie de votre application vers laquelle la requête est acheminée. Bien que pourrait potentiellement également passer un ensemble de paramètres de longueur variable à travers l'url:

GET somedomain.com/states/Virginia,California,Mississippi/

Un bon livre à lire comme introduction sur ce sujet est "Restful Web Services" . Bien que je vais vous avertir d'être prêt à écrémer sur certaines informations redondantes.

Je pense que ça dépend. Une URL pour une ressource. Si vous souhaitez recevoir cette ressource d'une manière légèrement différente, donnez-lui une chaîne de requête. Mais pour une valeur qui fournirait une ressource différente, mettez - la dans le chemin.

Ainsi, dans votre exemple, la valeur de la variable est directement liée à la ressource renvoyée. Donc, il est plus logique dans le chemin.

La première variation est un peu plus propre, et vous permet de réserver les paramètres de requête pour des choses comme l'ordre de tri et la page, comme dans

http://www.rest.services.com/items/b?sort=ascending;page=6

C'est une grande question fondamentale. Je suis récemment arrivé à la conclusion de rester à l'écart de l'utilisation des paramètres de chemin. Ils conduisent à une résolution ambiguë des ressources. L'URL est essentiellement le "nom de la méthode" d'un morceau de code s'exécutant quelque part sur un serveur. Je préfère ne pas mélanger les noms de variables avec les noms de méthodes. Le nom de votre méthode est apparemment 'client' (qui à mon humble avis est un nom pourri pour une méthode mais les gens de repos aiment ce modèle). Le paramètre que vous passez à cette méthode est le nom de client. Un paramètre de requête fonctionne bien pour cela, et cette valeur de ressource et de paramètre de requête peut même être mise en cache si vous le souhaitez.

Il n'y a pas de ressource client informatique physique. Il n'y a probablement aucun fichier sur le disque sous un dossier client nommé d'après le client. C'est un service web qui effectue une sorte de transaction de base de données. La "ressource" est votre service, pas le client.

Cette obsession pour le repos et les verbes web me rappelle les premiers jours de L'orienté objet programmation où nous avons tenté d'entasser notre code dans des représentations virtuelles d'objets physiques. Ensuite, nous avons réalisé que les objets sont généralement des concepts virtuels dans un système. OO est toujours utile lorsqu'il est fait de la bonne façon. REST est également utile si vous réalisez que les ressources RESTful sont des services, pas des objets.