Diverses pratiques REST suggèrent (par exemple, 1 < / a>, 2 , 3 ) pour utiliser des pluriels dans votre endpoints et le résultat est toujours une liste d'objets, sauf si elle est filtrée par une valeur spécifique, telle que / users / 123 Les paramètres de requête sont utilisés pour filtrer la liste, mais aboutissent néanmoins à une liste. Je veux savoir si mon cas devrait «abandonner» ces bonnes pratiques.
Utilisons les voitures pour mon exemple ci-dessous.
J'ai une base de données pleine de voitures et chacune a un BuildNumber ("Id"), mais aussi un modèle et une année de construction dont la combinaison est unique. Si j'interroge ensuite / cars / et recherche un modèle et une année spécifiques, par exemple / cars? Model = golf & year = 2018 , je sais, d'après ma phrase précédente, ma récupération contiendra toujours un seul objet, jamais plusieurs. Mon résultat, cependant, sera toujours une liste, contenant un seul objet, néanmoins.
Dans ce cas, quelle sera la meilleure pratique comme ci-dessus signifierait que l'objet doit être extrait de la liste, même si un seul objet aurait pu être renvoyé à la place.
/ car / et utilisez les paramètres de requête ? model = golf & year = 2018 , qui sont principalement utilisés pour filtrer dans une liste, et obtenez le résultat être un objet unique, comme l’indique le point de terminaison singulier La raison pour laquelle je pose cette question est simplement pour la propreté de l'action: je suis sûr à 100% que ma requête GET aboutira à un objet unique, mais je dois encore effectuer des actions pour l'extraire de la liste. Ces étapes auraient dû être inutiles. En dehors de cela, dans mon cas, je ne connais pas l'identifiant unique, donc cars / 123 pour récupérer une voiture spécifique n'est pas une option. Je connais, cependant, des filtres qui résulteront en un objet et un objet spécifique en tout. Les étapes supplémentaires semblent tout simplement redondantes.
1: https://docs.microsoft .com / fr-fr / azure / architecture / best-practices / api-design
2: https: // blog .mwaysolutions.com / 2014/06/05/10-best-practices-for-better-reposful-api /
3: https://medium.com/hashmapinc/rest- bonnes-pratiques-pour-la-conception-d'api-881439796dc9
3 Réponses :
1) Si vous utilisez une requête comme voitures / where ... - utilisez CARS
2) Si vous voulez CAR - méthode make GetCarById
Vous suggérez de vous en tenir à la liste, puisque j'utilise des paramètres de requête? Je ne filtre pas par ID, car je ne connais pas cette valeur; Pourtant, je sais que mes filtres résulteront en un seul objet.
Il ne s'agit pas de vous maintenant résultat ou non, il s'agit de la convention d'ensemble de résultats. Si le jeu de résultats peut retourner le tableau - c'est toujours CARS
Vous n'obtiendrez peut-être pas une réponse parfaite à cette question, car tout sera un peu subjectif et souvent d'une manière différente.
Ma pensée générale à ce sujet est que chaque élément de mon système aura sa propre URL unique, par exemple / cars / 1234 . Ce cas est toujours singulier.
Mais cet élément spécifique peut apparaître en tant que membre dans les collections et les résultats de recherche. Lorsque / cars / 1234 apparaît dans ceux-ci, ils apparaîtront toujours sous forme de liste avec 1 élément (ou 0 ou plus selon la requête).
Je pense que c'est finalement le plus prévisible.
Dans mon cas cependant, si une voiture apparaît comme membre d'une recherche ou d'une colletion, sa "vraie URL" sera toujours affichée.
Comme vous avez spécifiquement demandé les meilleures pratiques en matière de REST:
REST ne se soucie pas de la façon dont vous spécifiez vos URI ou du fait que des jetons sémantiquement significatifs sont utilisés à l'intérieur de l'URI. De plus, un client doit ne jamais s'attendre à ce qu'un certain URI soit renvoyé un certain type , mais reposent plutôt sur la négociation du type de contenu pour indiquer au serveur toutes les fonctionnalités prises en charge par le client.
De plus, vous ne devriez pas penser à REST en termes d’orientation objet, mais plutôt en termes de les moyens financiers et statemachines où un client reçoit toutes les informations nécessaires pour prendre une décision éclairée sur la marche à suivre.
Le meilleur exemple à donner ici est probablement de regarder de près le Web et la façon dont il est fait pour les pages HTML. Comment filtrer pour une voiture spécifique et comment elle vous sera présentée? Les mêmes concepts qui sont utilisés dans le Web s'appliquent également à REST car les deux utilisent le même modèle d'interaction. En ce qui concerne votre échantillon de voiture, l'API devrait initialement renvoyer des structures de contrôle qui enseignent au client comment une demande doit être formée et quelles options peuvent être filtrées. En HTML, cela se fait via des formulaires. Pour les API REST non HTML, il convient de définir des types de supports dédiés qui traduisent la même approche des structures non HTML. Lors de l'envoi de la demande au serveur, votre client inclura tous les types de supports pris en charge qu'il prend en charge dans un en-tête HTTP Accept , qui informe le serveur des capacités du client. Les types de média ne sont que des spécifications lisibles par l'homme sur la façon de traiter les charges utiles de ces types. Ces spécifications peuvent inclure des indications sur les informations de type qu'une relation de lien pourrait renvoyer . Afin d'obtenir une large utilisation des types de supports, ils doivent être définis comme génériques que possible. Au lieu de définir un type de média spécifique pour une voiture, ce qui est possible, il serait probablement plus pratique d'utiliser un format existant ou de définir un nouveau format de conteneur de données général (similaire au HTML).
Toutes les étapes mentionnées ici devraient vous aider à concevoir et à mettre en œuvre une API qui évolue librement sans risquer de casser des clients, qui est également évolutive et minimise les problèmes d'interopérabilité.
Malheureusement, votre question cible quelque chose de totalement différent IMO, quelque chose de plus lié au RPC. Vous invoquez essentiellement une méthode générique via HTTP sur un point de terminaison, similaire au travail SOAP, RMI ou CORBA. Que vous respectiez ou non la sémantique des opérations HTTP n'est que sous-intérêt ici. Même si vous avez atteint le niveau 3 du Richardson Maturity Model (RMM) , cela ne signifie pas que vous êtes conforme à REST. Votre client peut encore s'arrêter si le serveur modifie quoi que ce soit dans la réponse. Le RMM ne considère même pas du tout les types de médias, donc je le considère comme plutôt inutile.
Cependant, que vous utilisiez un (vrai) client REST ou RPC / CRUD, si vous préférez récupérer des éléments uniques au lieu de les alimenter dans une collection, vous devriez envisager d'inclure l'URI des éléments d'intérêt au lieu de ses données directement dans la collection, comme Evert l'a également suggéré. Alors que la plupart des gens semblent préoccupés par les performances du serveur et les temps d'aller-retour, il est en fait très élégant en termes de mise en cache. En outre, certains noms de relations de lien tels que prefetch peut informer le client qu'il peut récupérer la charge utile des cibles plus tôt car il est fort possible que son contenu soit demandé ensuite. Grâce à la mise en cache, une requête n'a peut-être même pas besoin d'être déclenchée ou envoyée au serveur pour traitement, ce qui est probablement le meilleur gain de performances que vous puissiez obtenir.