Nous lançons une nouvelle API REST et je voulais des commentaires de la communauté sur les meilleures pratiques concernant la façon dont nous devrions formater les paramètres d'entrée:
À l'heure actuelle, notre API est très centrée sur JSON (ne renvoie que JSON). Le débat de savoir si nous voulons / devons renvoyer XML est une question distincte.
Comme notre sortie API est centrée sur JSON, nous avons emprunté un chemin où nos entrées sont un peu centrées sur JSON et j'ai pensé que cela pourrait être pratique pour certains mais bizarre en général.
Par exemple, pour obtenir quelques détails sur les produits où plusieurs produits peuvent être extraits en même temps, nous avons actuellement:
http://our.api.com/Product?id=["101404","7267261"]
Faut-il simplifier cela comme:
http://our.api.com/Product?id=101404,7267261
Ou bien avoir une entrée JSON à portée de main? Plus de douleur?
Nous pouvons vouloir accepter les deux styles, mais cette flexibilité provoque-t-elle réellement plus de confusion et de maux de tête (maintenabilité, documentation, etc.)?
Un cas plus complexe est celui où nous voulons offrir des entrées plus complexes. Par exemple, si nous voulons autoriser plusieurs filtres sur la recherche:
http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}
Nous ne voulons pas nécessairement mettre les types de filtres (par exemple productType et color) en tant que noms de requête comme ceci:
http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]
Parce que nous voulions regrouper toutes les entrées de filtre.
En fin de compte, est-ce vraiment important? Il est probable qu'il y ait tellement d'utilitaires JSON que le type d'entrée n'a pas beaucoup d'importance.
Je sais que nos clients JavaScript effectuant des appels AJAX à l'API peuvent apprécier les entrées JSON pour leur faciliter la vie.
[]
syntaxe n'est pas toujours prise en charge (et bien qu'elle soit courante, elle peut même violer la spécification URI). Certains serveurs HTTP et langages de programmation préféreront simplement répéter le nom (par exempleproductType=value1&productType=value2
)./user/
et dans le corps, je vais envoyer{ q:{}, d: {} }
avecq
comme requête par avec l'utilisateur sera interrogé dans la base de données et end
tant que données modifiées.La manière standard de passer une liste de valeurs en tant que paramètres d'URL est de les répéter:
http://our.api.com/Product?id=101404&id=7267261
La plupart des codes de serveur interpréteront cela comme une liste de valeurs, bien que beaucoup aient des simplifications à valeur unique, vous devrez donc aller chercher.
Les valeurs délimitées sont également correctes.
Si vous devez envoyer du JSON au serveur, je n'aime pas le voir dans l'URL (qui est d'un format différent). En particulier, les URL ont une limitation de taille (en pratique sinon en théorie).
La façon dont j'ai vu certains effectuer une requête compliquée RESTfully se déroule en deux étapes:
POST
vos exigences de requête, recevoir un identifiant (essentiellement créer une ressource de critères de recherche)GET
la recherche, en faisant référence à l'ID ci-dessusla source
Première:
Je pense que vous pouvez le faire de 2 façons
http://our.api.com/Product/<id>
: si vous voulez juste un disquehttp://our.api.com/Product
: si vous voulez tous les enregistrementshttp://our.api.com/Product/<id1>,<id2>
: comme James l'a suggéré peut être une option car ce qui vient après la balise Product est un paramètreOu celui que j'aime le plus est:
Vous pouvez utiliser la propriété Hypermedia comme moteur d'état de l'application (HATEOAS) d'un WS RestFul et effectuer un appel
http://our.api.com/Product
qui doit renvoyer les URL équivalentes dehttp://our.api.com/Product/<id>
et les appeler après cela.Seconde
Lorsque vous devez faire des requêtes sur les appels URL. Je suggère d'utiliser à nouveau HATEOAS.
1) Appelez le
http://our.api.com/term/pumas/productType/clothing/color/black
2) Appelez le
http://our.api.com/term/pumas/productType/clothing,bags/color/black,red
3) (Utilisation de HATEOAS) Appelez ` http://our.api.com/term/pumas/productType/ -> recevez les urls tous les vêtements possibles urls -> appelez ceux que vous voulez (vêtements et sacs) - > recevoir les URL de couleur possibles -> appeler celles que vous voulez
la source
Vous voudrez peut-être consulter la RFC 6570 . Cette spécification de modèle d'URI montre de nombreux exemples de la façon dont les URL peuvent contenir des paramètres.
la source
Premier cas:
Une recherche de produit normale ressemblerait à ceci
http://our.api.com/product/1
Donc je pense que la meilleure pratique serait que vous fassiez cela
http://our.api.com/Product/101404,7267261
Deuxième cas
Recherche avec des paramètres de chaîne de requête - très bien comme ça. Je serais tenté de combiner des termes avec ET et OU au lieu d'utiliser
[]
.PS Cela peut être subjectif, alors faites ce avec quoi vous vous sentez à l'aise.
La raison pour laquelle les données sont placées dans l'URL est que le lien puisse être collé sur un site / partagé entre les utilisateurs. Si ce n'est pas un problème, utilisez plutôt un JSON / POST à la place.
EDIT: Après réflexion, je pense que cette approche convient à une entité avec une clé composée, mais pas une requête pour plusieurs entités.
la source
/
ne doit pas être là car l'URI adresse une ressource, pas une collection.Je me rallierai à la réponse de nategood car elle est complète et elle semble avoir satisfait vos besoins. Cependant, je voudrais ajouter un commentaire sur l'identification de plusieurs ressources (1 ou plus) de cette façon:
http://our.api.com/Product/101404,7267261
Ce faisant, vous:
Complexifiez les clients en les forçant à interpréter votre réponse comme un tableau, ce qui pour moi est contre-intuitif si je fais la demande suivante:
http://our.api.com/Product/101404
Créer des API redondantes avec une seule API pour obtenir tous les produits et celle ci-dessus pour en obtenir 1 ou plusieurs. Étant donné que vous ne devez pas montrer plus d'une page de détails à un utilisateur pour le bien de l'UX, je pense qu'avoir plus de 1 ID serait inutile et purement utilisé pour filtrer les produits.
Ce n'est peut-être pas si problématique, mais vous devrez soit le gérer vous-même côté serveur en renvoyant une seule entité (en vérifiant si votre réponse en contient une ou plusieurs), soit laisser les clients la gérer.
Exemple
Je veux commander un livre chez Amazing . Je sais exactement de quel livre il s'agit et je le vois dans la liste lors de la navigation pour les livres d'horreur:
Après avoir sélectionné le deuxième livre, je suis redirigé vers une page détaillant la partie livre d'une liste:
Ou dans une page me donnant tous les détails de ce livre uniquement?
Mon avis
Je suggère d'utiliser l'ID dans la variable path lorsque l'unicité est garantie lors de l'obtention des détails de cette ressource. Par exemple, les API ci-dessous suggèrent plusieurs façons d'obtenir les détails d'une ressource spécifique (en supposant qu'un produit a un ID unique et une spécification pour ce produit a un nom unique et vous pouvez naviguer de haut en bas):
Au moment où vous avez besoin de plus d'une ressource, je vous suggère de filtrer à partir d'une plus grande collection. Pour le même exemple:
Bien sûr, c'est mon avis car il n'est pas imposé.
la source