REST API - должен ли API возвращать вложенные объекты JSON?

Когда дело доходит до API JSON, рекомендуется ли выравнивать ответы и избегать вложенных объектов JSON?

В качестве примера, скажем, у нас есть API, похожий на IMDb, но для видеоигр. Существует пара сущностей: Game, Platform, 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 может быть гораздо больше информации, чем вы бы хотели загрузить в список игр.

Это один из основных вопросов, касающихся дизайна REST API. Каждый дизайнер задает себе этот вопрос в первый день. Извините, но ответ "это зависит". У каждого подхода есть свои плюсы и минусы, и вам просто нужно принять решение и пойти с ним.

Я второй подход, представленный здесь https://www.slideshare.net/stormpath/rest-jsonapis

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

На мой взгляд, это эффективный и гибкий способ в большинстве случаев.