API REST - Чи повинен API повертати вкладені JSON об'єкти?

Якщо мова заходить про API JSON, чи корисна практика вирівняти відповіді та уникати вкладених JSON-об'єктів?

Як приклад, можна сказати, що у нас є API, схожий на IMDb, але для відеоігор. Є кілька об'єктів, ігри, платформи, ESRBRating та GamePlatformMap, які відображають ігри та платформи.

Скажімо, ви вимагаєте / game / 1, яка отримує гру з ідентифікатором 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.

Інший варіант - просто API та додавання більшої кількості кінцевих точок.

У тому випадку, коли / game / 1 запитується, просто повертається ігровий об’єкт.

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

Якщо ви хочете, щоб платформи та / або ESRBRating вам доведеться зателефонувати наступним чином:

/ гра / 1 / платформа / гра / 1 / esrb

Цей метод, здається, може потенційно додати ще кілька дзвінків на сервер залежно від того, які дані потрібні клієнту та коли вони потребують.

Була одна остання думка, що я мав, де ти повернеш щось подібне.

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

Однак це передбачає, що їм не потрібні ідентифікатори або будь-яка інша інформація, яка може бути пов’язана з цими об'єктами платформи.

Я взагалі запитую, який найкращий спосіб структурувати свої об’єкти JSON, повернені з вашого API. Якщо ви намагаєтесь залишатися якомога ближче до своїх організацій, або добре використовувати об’єкти домену або об’єкти передачі даних? Я розумію, що методи матимуть компроміси, або більше роботи над рівнем доступу до даних, або більше роботи для клієнта.

Я також хотів би почути відповідь, пов’язаний із використанням Spring MVC як резервної технології для API, з JPA / Hibernate або MyBatis для постійності.

Ще одна альтернатива (з використанням HATEOAS). Це просто, в основному на практиці ви додаєте тег посилань у json залежно від використання 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: [] },
  ]
}

Ви можете, звичайно, вставляти всі дані у всі листи, але це, ймовірно, буде занадто багато даних. Таким чином ви можете вбудовувати потрібні дані, а потім завантажувати більше, якщо дійсно хочете працювати з ними.

Технічна реалізація може містити кешування. Ви можете кешувати посилання на платформи та назви в ігровому об’єкті та надсилати їх миттєво, не завантажуючи api платформ взагалі. Тоді, коли потрібно, ви можете завантажити його.

Ви бачите, наприклад, що я додав інформацію про форму. Я зробив це, щоб показати вам, що в детальному json-об'єкті може бути набагато більше інформації, ніж ви хотіли б навіть завантажувати в список ігор.

Це одне з основних питань, що стосується дизайну API REST. Кожен дизайнер задає собі це питання в перший день. Вибачте, але відповідь "це залежить". У кожного підходу є плюси і мінуси, і вам просто потрібно буде прийняти рішення і піти з ним.

Я другий підхід, представлений тут https://www.slideshare.net/stormpath/rest-jsonapis

Коротше кажучи, включіть вкладений ресурс як посилання на батьківський ресурс, тим часом надайте параметр розширення у батьківській кінцевій точці.

На мою думку, це спосіб, який у більшості випадків є ефективним та гнучким.