API REST: l'API deve restituire oggetti JSON nidificati?

Quando si tratta di API JSON è buona norma appiattire le risposte ed evitare oggetti JSON nidificati?

Ad esempio, diciamo che abbiamo un'API simile a IMDb ma per i videogiochi. Esistono un paio di entità, Game, Platform, ESRBRating e GamePlatformMap che mappano giochi e piattaforme.

Diciamo che richiedi / game / 1 che recupera il gioco con ID 1 e restituisce l'oggetto di gioco con le piattaforme ed esrbRating nidificato.

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

Se stai usando qualcosa come JPA / Hibernate, potrebbe farlo automaticamente se impostato su FETCH.EAGER.

L'altra opzione è semplicemente l'API e aggiungere più punti finali.

In tal caso quando viene richiesto / game / 1 viene restituito solo l'oggetto del gioco.

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

Se vuoi le piattaforme e / o ESRBRating dovresti chiamare il seguente:

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

Questo metodo sembra che potrebbe potenzialmente aggiungere molte più chiamate al server a seconda dei dati di cui il client ha bisogno e quando ne hanno bisogno.

Ci fu un ultimo pensiero che avevo dove avresti restituito qualcosa del genere.

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

Tuttavia, ciò presuppone che non siano necessari gli ID o qualsiasi altra informazione possa essere associata a tali oggetti della piattaforma.

Chiedo in generale qual è il modo migliore per strutturare gli oggetti JSON restituiti dall'API. Dovresti cercare di stare il più vicino possibile alle tue entità, o è bene usare oggetti di dominio o oggetti di trasferimento dati? Comprendo che i metodi avranno dei compromessi, o più lavoro sul livello di accesso ai dati o più lavoro per il cliente.

Vorrei anche sentire una risposta relativa all'uso di Spring MVC come tecnologia di back-end per l'API, con JPA / Hibernate o MyBatis per la persistenza.

Un'altra alternativa (usando HATEOAS). Questo è semplice, soprattutto nella pratica si aggiunge un tag link nel json a seconda dell'uso di 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: [] },
  ]
}

Puoi ovviamente incorporare tutti i dati in tutti gli elenchi, ma probabilmente saranno troppi dati. In questo modo è possibile incorporare i dati richiesti e quindi caricarne di più se si desidera davvero utilizzarli.

L'implementazione tecnica può contenere la memorizzazione nella cache. Puoi memorizzare nella cache i collegamenti e i nomi delle piattaforme nell'oggetto di gioco e inviarlo all'istante senza dover caricare le piattaforme api. Quindi, quando necessario, è possibile caricarlo.

Vedi ad esempio che ho aggiunto alcune informazioni sul modulo. L'ho fatto per mostrarti che in un oggetto json dettagliato possono esserci molte più informazioni di quelle che vorresti caricare nell'elenco dei giochi.

Questa è una di quelle domande di base quando si tratta della progettazione dell'API REST. Ogni designer si pone questa domanda il primo giorno. Siamo spiacenti ma la risposta è "dipende". Ogni approccio ha pro e contro e dovrai solo prendere una decisione e seguirla.

Secondo, l'approccio presentato qui https://www.slideshare.net/stormpath/rest-jsonapis

In breve, includere la risorsa nidificata come collegamenti nella risorsa padre, nel frattempo fornire un parametro di espansione nell'endpoint padre.

Secondo me, questo è un modo che è efficiente e flessibile nella maggior parte dei casi.