API REST - L'API doit-elle renvoyer des objets JSON imbriqués?

En ce qui concerne les API JSON, est-il recommandé d’aplanir les réponses et d’éviter les objets JSON imbriqués?

Par exemple, disons que nous avons une API similaire à IMDb mais pour les jeux vidéo. Il existe plusieurs entités, Game, Platform, ESRBRating et GamePlatformMap, qui mappent les jeux et les plates-formes.

Disons que vous demandez / jeu / 1 qui va chercher le jeu avec l'ID 1 et qu'il retournera l'objet du jeu avec les plateformes et esrbRating imbriquées.

{
  "id": 1,
  "title": "Game A",
  "publisher": "Publisher ABC",
  "developer": "Developer DEF",
  "releaseDate": "2015-01-01",
  "platforms": [
    {"id":1,"name":"Xbox"},
    {"id":2,"name":"Playstation"}
  ],
  "esrbRating": {
    "id": 1,
    "code": "E",
    "name": "Everyone"
  }
}

Si vous utilisez quelque chose comme JPA / Hibernate, il peut le faire automatiquement s'il est défini sur FETCH.EAGER.

L'autre option consiste à simplement utiliser l'API et à ajouter davantage de points d'extrémité.

Dans ce cas, lorsque / game / 1 est demandé, seul l'objet game est renvoyé.

{
  "id": 1,
  "title": "Game A",
  "publisher": "Publisher ABC",
  "developer": "Developer DEF",
  "releaseDate": "2015-01-01",
}

Si vous souhaitez les plates-formes et / ou ESRBRating, vous devez appeler le numéro suivant:

/ jeu / 1 / plateforme / jeu / 1 / esrb

Cette méthode semble potentiellement ajouter plusieurs appels supplémentaires au serveur, en fonction des données dont le client a besoin et du moment où il en a besoin.

Il y avait une dernière pensée que j'avais où vous auriez quelque chose comme ceci retourné.

{
  "id": 1,
  "title": "Game A",
  "publisher": "Publisher ABC",
  "developer": "Developer DEF",
  "releaseDate": "2015-01-01",
  "platforms": ["Xbox","Playstation"]
}

Toutefois, cela suppose qu'ils n'ont pas besoin des ID ou de toute autre information pouvant être associée à ces objets de plate-forme.

Je demande en général quel est le meilleur moyen de structurer vos objets JSON renvoyés par votre API. Devriez-vous essayer de rester aussi proche que possible de vos entités, ou est-il préférable d'utiliser des objets de domaine ou des objets de transfert de données? Je comprends que les méthodes auront des compromis, soit plus de travail sur la couche d'accès aux données, soit plus de travail pour le client.

J'aimerais également entendre une réponse relative à l'utilisation de Spring MVC en tant que technologie de base pour l'API, avec JPA / Hibernate ou MyBatis pour la persistance.

Une autre alternative (en utilisant HATEOAS). C’est simple, dans la pratique, vous ajoutez une balise links dans le JSON en fonction de votre utilisation de HATEOAS.

http://api.example.com/games/1:

{
  "id": 1,
  "title": "Game A",
  "publisher": "Publisher ABC",
  "developer": "Developer DEF",
  "releaseDate": "2015-01-01",
  "platforms": [
    {"_self": "http://api.example.com/games/1/platforms/53", "name": "Playstation"},
    {"_self": "http://api.example.com/games/1/platforms/34", "name": "Xbox"},
  ]
}

http://api.example.com/games/1/platforms/34:

{
  "id": 34,
  "title": "Xbox",
  "publisher": "Microsoft",
  "releaseDate": "2015-01-01",
  "testReport": "http://api.example.com/games/1/platforms/34/reports/84848.pdf",
  "forms": [
    {"type": "edit", "fields: [] },
  ]
}

Vous pouvez bien sûr intégrer toutes les données dans toutes les listes, mais ce sera probablement trop de données. De cette façon, vous pouvez incorporer les données requises, puis en charger davantage si vous voulez vraiment les utiliser.

L'implémentation technique peut contenir une mise en cache. Vous pouvez mettre en cache les liens et les noms de plates-formes dans l'objet de jeu et l'envoyer instantanément sans avoir à charger l'API de plates-formes. Ensuite, si nécessaire, vous pouvez le charger.

Vous voyez par exemple que j'ai ajouté des informations de formulaire. J'ai fait cela pour vous montrer qu'il peut y avoir beaucoup plus d'informations dans un objet json détaillé que vous ne voudriez même charger dans la liste des jeux.

C'est l'une de ces questions fondamentales en matière de conception des API REST. Chaque designer se pose cette question le premier jour. Désolé mais la réponse est "ça dépend". Chaque approche a ses avantages et ses inconvénients et il vous suffit de prendre une décision et de l'accepter.

J'approuve l'approche présentée ici https://www.slideshare.net/stormpath/rest-jsonapis

En bref, incluez la ressource imbriquée en tant que liens dans la ressource parente, fournissez un paramètre de développement dans le noeud final parent.

À mon avis, c’est un moyen efficace et flexible dans la plupart des cas.