Concevoir une API REST avec des relations de ressources?

Question

Je travaille à concevoir une API REST à utiliser par un SPA React.

Le côté client du SPA interroge les données sur une relation entre deux entités: Team et Player où Teams a plusieurs Player et Player ne peut appartenir qu'à un seul Team.

Je veux interroger tous les Team et ensuite obtenir tous les Player pour chaque équipe (ce qui pourrait être un cas d'utilisation assez typique pour ces ressources dans un SPA).

je peux voir 3 approches principales:

1. Élargir le /teams endpoint pour avoir un paramètre ?expand=player ou quelque chose de similaire qui inclut un tableau de joueurs pour chaque équipe. Les données reviennent Nice pour être consommées par l'application React mais maintenant le point de terminaison API REST devient de plus en plus complexe et moins conforme au principe de responsabilité unique.

2. Requete /teams pour obtenir les ID de toutes les équipes, puis interroger chaque équipe /team/:id/players. Mais cela augmentera le nombre de requêtes vers le backend, même si cela séparera les responsabilités plus agréablement et rendra les choses plus explicites.

3. Requete /teams pour obtenir les ID de toutes les équipes, puis interroger /players/:ids où :ids est l'ID de toutes les équipes. Ceci est également assez explicite, mais pourrait entraîner une URL énorme et n'est pas agréable et bien rangé.

Quelle approche est généralement considérée comme la meilleure? Bien sûr, tous ont des compromis, mais peut-être que je néglige certains compromis?

Answer 1

Je veux interroger toutes les équipes, puis obtenir tous les joueurs de chaque équipe

Comment le feriez-vous en tant que site Web?

Si vous n'essayez pas de créer une "API REST", vous créerez probablement une seule page html contenant toutes les données souhaitées; un aller chercher du client, et tada, vous avez terminé.

S'il y avait beaucoup de données, vous pouvez les livrer sous forme de plusieurs pages, liées entre elles.

Mais de toute façon, ce ne serait qu'un gros bloc de code HTML, que les clients pourraient retirer en obtenant le lien.

L'orthographe du lien est-elle importante? Pas au client, ils vont juste le chercher. Le serveur doit être en mesure de faire correspondre le bon HTML au lien, mais le serveur peut le faire comme bon lui semble.

Donc, si vous souhaitez mettre cette page dans votre hiérarchie /teams, Ou dans votre hiérarchie /players, Ou dans une /league, /reports Ou /views Hiérarchie, ce sont tous des choix parfaits.

Le fait que la représentation que vous utilisez est un document JSON, plutôt que HTML, ou XML, ou autre, ne change rien à cela.

Une partie de l'intérêt de REST est que ce n'est pas important que le client puisse démonter votre URI et en déduire votre schéma de base de données.

Ce que le serveur fait réellement pour trouver la représentation correcte est un détail d'implémentation que nous cachons derrière l'interface uniforme.

Answer 2

Cela dépend des fonctions des clients de l'application, de la quantité de données et des performances de traitement des demandes.

Si tous les joueurs de toutes les équipes sont toujours requis, incluez la collection de joueurs dans chaque ressource d'équipe qui est retournée.

Si les détails des joueurs ne sont pas toujours requis, chaque équipe peut inclure la collecte de tous les identifiants des joueurs et récupérer les détails si nécessaire.

Si les joueurs ne sont pas requis pour toutes les fonctions de l'application où les équipes sont traitées, obtenez des joueurs au besoin.

Mais l'URL n'est pas vraiment importante. Pour une API REST, il est plus important de définir comment les clients découvrent quelles URL existent pour effectuer des actions sur les ressources, en fonction de leur type MIME. Il s'agit des HATEOAS (Hypermedia As The Engine Of Application State) fait partie de REST.

Answer 3

Je pense que l'option # 2 est la plus simple à comprendre, à implémenter et à maintenir, car vous pouvez la construire en plus de certaines opérations CRUD très basiques, qui pourraient également être réutilisables dans d'autres cas.

Il en résultera plus de demandes à votre serveur, mais vous pouvez probablement les traiter de manière asynchrone et en parallèle, donc l'application sera toujours réactive.

Si votre backend a une bonne mise à l'échelle horizontale, le fait d'avoir des demandes plus petites peut en fait vous donner de meilleures performances.