REST API - Haruskah API Mengembalikan Objek JSON Bersarang?

Ketika datang ke API JSON apakah itu praktik yang baik untuk meratakan respons dan menghindari objek JSON bersarang?

Sebagai contoh katakanlah kita memiliki API yang mirip dengan IMDb tetapi untuk video game. Ada beberapa entitas, Game, Platform, ESRBRating, dan GamePlatformMap yang memetakan Game dan Platform.

Katakanlah Anda meminta / game / 1 yang mengambil game dengan ID 1 dan mengembalikan objek game dengan platform dan menghindari sarang.

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

Jika Anda menggunakan sesuatu seperti JPA / Hibernate, ini dapat secara otomatis melakukan ini untuk Anda jika diatur ke FETCH.EAGER.

Opsi lainnya adalah cukup dengan API dan menambahkan lebih banyak titik akhir.

Dalam hal ini ketika / game / 1 diminta hanya objek game dikembalikan.

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

Jika Anda ingin platform dan / atau ESRBRating, Anda harus memanggil yang berikut ini:

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

Metode ini sepertinya berpotensi menambah beberapa panggilan lagi ke server tergantung pada data apa yang dibutuhkan klien dan kapan mereka membutuhkannya.

Ada satu pikiran terakhir yang saya miliki di mana Anda akan mendapatkan sesuatu seperti ini kembali.

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

Namun ini mengasumsikan mereka tidak memerlukan ID atau informasi apa pun lainnya yang terkait dengan objek platform tersebut.

Saya bertanya secara umum apa cara terbaik untuk menyusun objek JSON Anda yang dikembalikan dari API Anda. Haruskah Anda mencoba untuk tetap sedekat mungkin dengan entitas Anda, atau apakah boleh menggunakan Objek Domain atau Objek Transfer Data? Saya mengerti metode ini akan memiliki pertukaran, baik lebih banyak pekerjaan pada lapisan akses data atau lebih banyak pekerjaan untuk klien.

Saya juga ingin mendengar jawaban terkait menggunakan Spring MVC sebagai teknologi backend untuk API, dengan JPA / Hibernate atau MyBatis untuk kegigihan.

Alternatif lain (menggunakan HATEOAS). Ini sederhana, sebagian besar dalam praktiknya Anda menambahkan tag tautan di json tergantung pada penggunaan HATEOAS Anda.

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

Tentu saja Anda dapat menyematkan semua data dalam semua cantuman, tetapi kemungkinan besar terlalu banyak data. Dengan cara ini Anda dapat menyematkan data yang diperlukan dan memuat lebih banyak jika Anda benar-benar ingin bekerja dengannya.

Implementasi teknis dapat berisi caching. Anda dapat men-cache link platform dan nama dalam objek game dan mengirimkannya langsung tanpa harus memuat api platform sama sekali. Kemudian saat dibutuhkan Anda bisa memuatnya.

Anda lihat misalnya bahwa saya menambahkan beberapa informasi formulir. Saya melakukan itu untuk menunjukkan kepada Anda bahwa ada lebih banyak informasi dalam objek json terperinci daripada yang ingin Anda muat dalam daftar permainan.

Ini adalah salah satu pertanyaan dasar ketika datang ke desain REST API. Setiap desainer bertanya pada diri sendiri pertanyaan ini pada hari pertama. Maaf tapi jawabannya "tergantung". Setiap pendekatan memiliki pro dan kontra dan Anda hanya perlu membuat keputusan dan mengikutinya.

Saya kedua pendekatan yang disajikan di sini https://www.slideshare.net/stormpath/rest-jsonapis

Singkatnya, sertakan sumber daya bersarang sebagai tautan di sumber daya induk, sementara itu, berikan parameter ekspansi di titik akhir induk.

Menurut pendapat saya, ini adalah cara yang efisien dan fleksibel dalam banyak kasus.