API REST: ¿la API debe devolver objetos JSON anidados?

Cuando se trata de API JSON, ¿es una buena práctica aplanar las respuestas y evitar objetos JSON anidados?

Como ejemplo, digamos que tenemos una API similar a IMDb pero para videojuegos. Hay un par de entidades, Juego, Plataforma, ESRBRating y GamePlatformMap que mapean Juegos y Plataformas.

Digamos que solicitas / game / 1 que obtiene el juego con ID 1 y devuelve el objeto del juego con las plataformas y esrbRating anidado.

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

Si está utilizando algo como JPA / Hibernate, puede hacerlo automáticamente si está configurado en FETCH.EAGER.

La otra opción es simplemente la API y agregar más puntos finales.

En ese caso, cuando se solicita / game / 1 solo se devuelve el objeto del juego.

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

Si desea que las plataformas y / o ESRBRating tengan que llamar a lo siguiente:

/ juego / 1 / plataforma / juego / 1 / esrb

Parece que este método podría agregar varias llamadas más al servidor dependiendo de qué datos necesita el cliente y cuándo lo necesitan.

Hubo un último pensamiento que tuve donde tendrías que devolver algo como esto.

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

Sin embargo, esto supone que no necesitan los ID o cualquier otra información que pueda estar asociada con esos objetos de la plataforma.

En general, pregunto cuál es la mejor manera de estructurar sus objetos JSON devueltos por su API. ¿Debería tratar de mantenerse lo más cerca posible de sus entidades, o está bien usar Objetos de dominio u Objetos de transferencia de datos? Entiendo que los métodos tendrán compensaciones, ya sea más trabajo en la capa de acceso a datos o más trabajo para el cliente.

También me gustaría escuchar una respuesta relacionada con el uso de Spring MVC como tecnología de back-end para la API, ya sea con JPA / Hibernate o MyBatis para la persistencia.

Otra alternativa (usando HATEOAS). Esto es simple, principalmente en la práctica agrega una etiqueta de enlaces en el json dependiendo de su uso de 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: [] },
  ]
}

Por supuesto, puede incrustar todos los datos en todos los listados, pero es probable que sean demasiados datos. De esta manera, puede incrustar los datos necesarios y luego cargar más si realmente desea trabajar con ellos.

La implementación técnica puede contener almacenamiento en caché. Puede almacenar en caché los enlaces y los nombres de las plataformas en el objeto del juego y enviarlo instantáneamente sin tener que cargar la API de la plataforma. Luego, cuando sea necesario, puede cargarlo.

Ves, por ejemplo, que agregué información de formulario. Lo hice para mostrarle que puede haber mucha más información en un objeto json detallado de lo que incluso querría cargar en la lista de juegos.

Esta es una de esas preguntas básicas cuando se trata del diseño de API REST. Cada diseñador se hace esta pregunta el primer día. Lo siento, pero la respuesta es "depende". Cada enfoque tiene ventajas y desventajas y solo tendrá que tomar una decisión e ir con ella.

Secundo el enfoque presentado aquí https://www.slideshare.net/stormpath/rest-jsonapis

En resumen, incluya el recurso anidado como enlaces en el recurso primario, mientras tanto, proporcione un parámetro de expansión en el punto final primario.

En mi opinión, esta es una forma eficiente y flexible en la mayoría de los casos.