REST-API - Soll die API geschachtelte JSON-Objekte zurückgeben?

Wenn es um JSON-APIs geht, ist es empfehlenswert, Antworten zu reduzieren und verschachtelte JSON-Objekte zu vermeiden?

Nehmen wir als Beispiel an, wir haben eine ähnliche API wie IMDb, jedoch für Videospiele. Es gibt ein paar Entitäten, Game, Platform, ESRBRating und GamePlatformMap, die Spiele und Plattformen zuordnen.

Nehmen wir an, Sie fordern / game / 1 an, das das Spiel mit der ID 1 abruft und das Spielobjekt mit den verschachtelten Plattformen und esrbRating zurückgibt.

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

Wenn Sie so etwas wie JPA / Hibernate verwenden, wird dies möglicherweise automatisch für Sie erledigt, wenn FETCH.EAGER eingestellt ist.

Die andere Option besteht darin, einfach die API zu verwenden und weitere Endpunkte hinzuzufügen.

In diesem Fall, wenn / game / 1 angefordert wird, wird nur das Spielobjekt zurückgegeben.

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

Wenn Sie die Plattformen und / oder ESRBRating möchten, müssen Sie Folgendes aufrufen:

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

Diese Methode könnte möglicherweise mehrere weitere Aufrufe an den Server senden, je nachdem, welche Daten der Client benötigt und wann er sie benötigt.

Es gab einen letzten Gedanken, den ich hatte, wo Sie so etwas zurückbekommen würden.

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

Dies setzt jedoch voraus, dass sie keine IDs oder andere Informationen benötigen, die diesen Plattformobjekten zugeordnet sind.

Ich frage allgemein, wie Sie die von Ihrer API zurückgegebenen JSON-Objekte am besten strukturieren können. Sollten Sie versuchen, so nah wie möglich an Ihren Entitäten zu bleiben, oder ist es in Ordnung, Domänenobjekte oder Datenübertragungsobjekte zu verwenden? Ich verstehe, dass die Methoden Kompromisse haben werden, entweder mehr Arbeit auf der Datenzugriffsebene oder mehr Arbeit für den Client.

Ich würde auch gerne eine Antwort bezüglich der Verwendung von Spring MVC als Back-End-Technologie für die API hören, entweder mit JPA / Hibernate oder MyBatis für die Persistenz.

Eine weitere Alternative (mit HATEOAS). Dies ist einfach, meistens fügen Sie in der Praxis einen Link-Tag in den JSON ein, abhängig von Ihrer Verwendung von 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: [] },
  ]
}

Sie können natürlich alle Daten in alle Auflistungen einbetten, aber das sind wahrscheinlich viel zu viele Daten. Auf diese Weise können Sie die erforderlichen Daten einbetten und dann mehr laden, wenn Sie wirklich damit arbeiten möchten.

Die technische Implementierung kann Caching enthalten. Sie können die Plattformlinks und -namen im Spielobjekt zwischenspeichern und sofort senden, ohne die Plattform-API laden zu müssen. Dann können Sie es bei Bedarf laden.

Sie sehen zum Beispiel, dass ich einige Formularinformationen hinzugefügt habe. Ich habe dies getan, um Ihnen zu zeigen, dass ein detailliertes JSON-Objekt viel mehr Informationen enthalten kann, als Sie in der Liste der Spiele laden möchten.

Dies ist eine der grundlegenden Fragen beim Entwurf von REST-APIs. Jeder Designer stellt sich diese Frage am ersten Tag. Sorry, aber die Antwort ist "es kommt darauf an". Jeder Ansatz hat Vor- und Nachteile, und Sie müssen nur eine Entscheidung treffen und mitmachen.

Ich schließe mich dem hier vorgestellten Ansatz an: https://www.slideshare.net/stormpath/rest-jsonapis

Schließen Sie die verschachtelte Ressource als Links in die übergeordnete Ressource ein. Stellen Sie währenddessen einen Erweiterungsparameter im übergeordneten Endpunkt bereit.

Meiner Meinung nach ist dies in den meisten Fällen ein effizienter und flexibler Weg.