API REST - A API deve retornar objetos JSON aninhados?

Quando se trata de APIs JSON, é uma boa prática achatar respostas e evitar objetos JSON aninhados?

Como exemplo, digamos que temos uma API semelhante à IMDb, mas para videogames. Existem algumas entidades, Game, Platform, ESRBRating e GamePlatformMap, que mapeiam Jogos e Plataformas.

Digamos que você solicite / game / 1, que busca o ID do jogo 1 e retorna o objeto do jogo com as plataformas e esrbRating aninhado.

{
  "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 você estiver usando algo como JPA / Hibernate, isso poderá ser feito automaticamente se estiver definido como FETCH.EAGER.

A outra opção é simplesmente a API e adicionar mais pontos finais.

Nesse caso, quando / game / 1 for solicitado, apenas o objeto do jogo será retornado.

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

Se você quiser as plataformas e / ou ESRBRating, precisará chamar o seguinte:

/ jogo / 1 / plataforma / jogo / 1 / esrb

Parece que esse método pode adicionar várias chamadas ao servidor, dependendo de quais dados o cliente precisa e quando precisa.

Houve um último pensamento que tive onde você teria algo assim retornado.

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

No entanto, isso pressupõe que eles não precisam dos IDs ou de qualquer outra informação que possa estar associada a esses objetos de plataforma.

Pergunto em geral qual é a melhor maneira de estruturar seus objetos JSON retornados da sua API. Você deve tentar ficar o mais próximo possível das suas entidades ou é bom usar objetos de domínio ou objetos de transferência de dados? Entendo que os métodos terão compensações, mais trabalho na camada de acesso a dados ou mais trabalho para o cliente.

Também gostaria de ouvir uma resposta relacionada ao uso do Spring MVC como a tecnologia de back-end da API, com JPA / Hibernate ou MyBatis para persistência.

Outra alternativa (usando HATEOAS). Isso é simples, principalmente na prática, você adiciona uma tag de links no json, dependendo do uso do 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: [] },
  ]
}

É claro que você pode incorporar todos os dados em todas as listagens, mas isso provavelmente será um excesso de dados. Dessa forma, você pode incorporar os dados necessários e, em seguida, carregar mais, se realmente quiser trabalhar com eles.

A implementação técnica pode conter armazenamento em cache. Você pode armazenar em cache os links e nomes das plataformas no objeto do jogo e enviá-lo instantaneamente sem precisar carregar a API da plataforma. Então, quando necessário, você pode carregá-lo.

Você vê, por exemplo, que adicionei algumas informações de formulário. Fiz isso para mostrar que pode haver muito mais informações em um objeto json detalhado do que você gostaria de carregar na lista de jogos.

Essa é uma dessas perguntas básicas quando se trata do design da API REST. Todo designer se faz essa pergunta no primeiro dia. Desculpe, mas a resposta é "depende". Cada abordagem tem prós e contras e você só precisa tomar uma decisão e seguir em frente.

Segundo a abordagem apresentada aqui https://www.slideshare.net/stormpath/rest-jsonapis

Em resumo, inclua o recurso aninhado como links no recurso pai, enquanto isso, forneça um parâmetro de expansão no terminal pai.

Na minha opinião, essa é uma maneira eficiente e flexível na maioria dos casos.