Interfejs API REST - czy interfejs API powinien zwracać zagnieżdżone obiekty JSON?

Jeśli chodzi o interfejsy API JSON, czy dobrą praktyką jest spłaszczanie odpowiedzi i unikanie zagnieżdżonych obiektów JSON?

Jako przykład powiedzmy, że mamy interfejs API podobny do IMDb, ale do gier wideo. Istnieje kilka encji: Gra, Platforma, ESRBRating i GamePlatformMap, która mapuje Gry i platformy.

Powiedzmy, że żądasz / game / 1, która pobiera grę o identyfikatorze 1 i zwraca obiekt gry z zagnieżdżonymi platformami i 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"
  }
}

Jeśli używasz czegoś takiego jak JPA / Hibernate, może to zrobić automatycznie, jeśli jest ustawiony na FETCH.EAGER.

Inną opcją jest po prostu interfejs API i dodanie kolejnych punktów końcowych.

W takim przypadku, gdy wymagane jest / game / 1, zwracany jest tylko obiekt gry.

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

Jeśli chcesz platformy i / lub ESRBRating, musisz zadzwonić pod następujący numer:

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

Wydaje się, że ta metoda może potencjalnie dodać kilka kolejnych wywołań do serwera, w zależności od danych potrzebnych klientowi i kiedy go potrzebuje.

Była jedna ostatnia myśl, w której chciałbym, żebyś wrócił coś takiego.

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

Zakłada się jednak, że nie potrzebują one identyfikatorów ani żadnych innych informacji powiązanych z tymi obiektami platformy.

Pytam ogólnie, jaki jest najlepszy sposób na uporządkowanie obiektów JSON zwróconych z interfejsu API. Czy powinieneś starać się być jak najbliżej swoich bytów, czy też dobrze jest używać Obiektów Domeny lub Obiektów Transferu Danych? Rozumiem, że metody będą miały kompromisy, albo więcej pracy na warstwie dostępu do danych, albo więcej pracy dla klienta.

Chciałbym również usłyszeć odpowiedź związaną z używaniem Spring MVC jako technologii zaplecza dla API, z JPA / Hibernate lub MyBatis dla trwałości.

Kolejna alternatywa (przy użyciu HATEOAS). Jest to proste, głównie w praktyce dodajesz znacznik links w pliku json, w zależności od korzystania z 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: [] },
  ]
}

Oczywiście możesz osadzić wszystkie dane na wszystkich listach, ale prawdopodobnie będzie to o wiele za dużo danych. W ten sposób możesz osadzić wymagane dane, a następnie załadować więcej, jeśli naprawdę chcesz z nimi pracować.

Techniczna implementacja może zawierać buforowanie. Możesz buforować linki i nazwy platform w obiekcie gry i wysyłać je natychmiast, bez konieczności wczytywania interfejsu API platform. W razie potrzeby można go załadować.

Widzisz na przykład, że dodałem informacje o formularzu. Zrobiłem to, aby pokazać, że w szczegółowym obiekcie Json może być znacznie więcej informacji, niż chciałbyś wczytać na liście gier.

To jedno z podstawowych pytań dotyczących projektowania interfejsu API REST. Każdy projektant zadaje sobie to pytanie już pierwszego dnia. Przepraszamy, ale odpowiedź brzmi „to zależy”. Każde podejście ma zalety i wady, a Ty musisz tylko podjąć decyzję i iść z nią.

Opieram się na przedstawionym tutaj podejściu https://www.slideshare.net/stormpath/rest-jsonapis

Krótko mówiąc, włącz zasób zagnieżdżony jako łącza do zasobu nadrzędnego, tymczasem podaj parametr rozwijania w nadrzędnym punkcie końcowym.

Moim zdaniem jest to sposób, który jest skuteczny i elastyczny w większości przypadków.