Para uma API REST em que estou trabalhando, desejo retornar o JSON em um layout consistente:
{
"Data" : {
"Id" : 123,
"Email" : "[email protected]"
"Firstname" : "Charlie",
"Surname" : "Brown",
},
"Error" : null
}
A carga útil sempre conterá "Dados" e "Erro", onde um ou outro pode ser nulo.
Minha pergunta diz respeito a "Dados" e pontos de extremidade que realmente retornam apenas um objeto. Por exemplo, digamos que eu tenho uma API users/current, que retorna o usuário autenticado no momento. Eu teria retornado esse usuário como mostrado acima; um único objeto JSON chamado "Dados".
Para terminais que poderiam retornar zero, um ou mais objetos, eu (é claro) tornaria "Dados" uma matriz:
{
"Data" : [
{
(first object)
},
{
(second object)
}
],
"Error" : null
}
Ouvi um ponto de vista de que, por consistência, "Dados" sempre deve ser uma matriz. Mesmo quando um ponto de extremidade logicamente retornaria apenas um único objeto (ou nulo).
O que os outros pensam? Eu acho que não há necessidade de criar "Data" e array se nunca haverá mais de um objeto retornado.
Respostas:
Eu acho que esse tipo de consistência é equivocado.
É improvável que agrupar os dados em uma matriz beneficie um consumidor de API, porque ele ainda precisará saber como interpretar os dados reais. Como exemplo, é pouco provável que os "dados" resultem
/users/currente/cities/chicago/restaurantssejam manipulados pelo mesmo código.Por outro lado, para erros, é provável que todos os erros sejam processados pelo mesmo código de tratamento de erros e, em seguida, há um benefício em usar a mesma estrutura.
Pergunte a si mesmo: se essa era uma classe no seu idioma favorito de POO, você faria com que todos os métodos retornassem o mesmo tipo de consistência?
fonte
/users/currente o usuário cujo ID (possivelmente nome de login) é "atual"?Se o lado receptor precisar de um destinatário geral para suas mensagens JSON, pode ser útil ter o nó de dados no mesmo formato. Portanto, nesse caso, é útil ter sempre uma matriz, para que possa ser analisada da mesma maneira sempre.
Se cada resposta for tratada individualmente (chamadas de API diferentes a partir de métodos diferentes), posso entender o seu ponto, no entanto , deve ficar absolutamente claro (a partir das chamadas de API) quando um array ou um objeto deve ser retornado.
fonte
Não sou fã da abordagem de matriz porque ela não oferece consistência verdadeira. Obriga o usuário do serviço a se perguntar sobre coisas como, o que acontece se houver mais de um objeto nessa matriz ou a se livrar do empacotamento matriz o mais rápido possível para essas matrizes singleton. Você ainda teria que fazer duas coisas diferentes.
No entanto, se você usar a matriz, verifique se Dados nunca é nulo. Se não houver dados, a matriz deve estar vazia. É a única vantagem que posso ver.
fonte
Estou caindo do lado de sempre retornar uma matriz. No lado do cliente, eu uso meu objeto de resposta "Usuários", seja para obter todos os usuários ou apenas um. Se você tiver um ponto de extremidade que retorna matrizes e outro que retorna o mesmo objeto, mas nunca mais que um, ainda use uma matriz.
Existem argumentos semelhantes para usar a mesma lógica no lado do servidor; basta usar o mesmo código, independentemente de sua consulta estar retornando um item ou vários.
A única exceção seria ao retornar um objeto que nunca existe como uma matriz, em qualquer contexto, então não há necessidade.
fonte