REST API-APIはネストされたJSONオブジェクトを返す必要がありますか？

JSON APIに関しては、応答をフラット化し、ネストされたJSONオブジェクトを避けるのが良いでしょうか？

例として、IMDbに似ているがビデオゲーム用のAPIがあるとします。いくつかのエンティティ、Game、Platform、ESRBRating、GamesとPlatformsをマップするGamePlatformMapがあります。

ID 1のゲームを取得する/ game / 1をリクエストすると、プラットフォームとesrbRatingがネストされたゲームオブジェクトを返します。

{
  "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"
  }
}

JPA / Hibernateのようなものを使用している場合、FETCH.EAGERに設定されていれば自動的にこれを行うことがあります。

もう1つのオプションは、単にAPIを追加して、エンドポイントを追加することです。

その場合、/ game / 1が要求されると、ゲームオブジェクトのみが返されます。

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

プラットフォームやESRBRatingが必要な場合は、次を呼び出す必要があります。

/ game / 1 / platform / game / 1 / esrb

このメソッドは、クライアントが必要とするデータと必要なタイミングに応じて、サーバーにさらにいくつかの呼び出しを追加する可能性があるようです。

最後に、このようなものが返されると思いました。

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

ただし、これは、IDやその他の情報がプラットフォームオブジェクトに関連付けられている必要がないことを前提としています。

一般に、APIから返されたJSONオブジェクトを構造化する最良の方法は何かを尋ねます。エンティティにできるだけ近づけるようにする必要がありますか、またはドメインオブジェクトまたはデータ転送オブジェクトを使用しても問題ありませんか？メソッドには、データアクセス層でのより多くの作業またはクライアントでのより多くの作業のいずれかのトレードオフがあることを理解しています。

また、APIのバックエンドテクノロジーとしてSpring MVCを使用し、永続化のためにJPA / HibernateまたはMyBatisのいずれかを使用することに関連した回答も聞きたいです。

別の選択肢（HATEOASを使用）。これは簡単で、ほとんどの場合、HATEOASの使用に応じてリンクタグをjsonに追加します。

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: [] },
  ]
}

もちろん、すべてのデータをすべてのリストに埋め込むこともできますが、データが多すぎる可能性があります。この方法で、必要なデータを埋め込み、それを本当に使いたい場合はさらに読み込むことができます。

技術的な実装にはキャッシュを含めることができます。プラットフォームAPIをまったくロードせずに、プラットフォームのリンクと名前をゲームオブジェクトにキャッシュし、即座に送信できます。その後、必要に応じてロードできます。

たとえば、フォーム情報を追加したことがわかります。詳細なjsonオブジェクトには、ゲームのリストにロードするよりもはるかに多くの情報が存在する可能性があることを示すために行いました。

これは、REST API設計に関する基本的な質問の1つです。すべてのデザイナーは、初日にこの質問を自問します。申し訳ありませんが、答えは「それは依存します」です。それぞれのアプローチには長所と短所があり、決定を下してそれを実行するだけです。

次に、https：//www.slideshare.net/stormpath/rest-jsonapisで提示されているアプローチ

つまり、ネストされたリソースを親リソースのリンクとして含め、一方、親エンドポイントに展開パラメーターを提供します。

私の意見では、これはほとんどの場合、効率的で柔軟な方法です。