É uma boa prática fazer a lista de valores de resposta da API como dicionário?

Eu tenho um ponto de extremidade da API que retorna algumas estatísticas. Atualmente, a resposta se parece com:

Opção 1:

{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ],
    ... other keys
}

Mas isso parece um pouco complexo e eu como fazê-lo:

Opção 2:

{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
    ... other keys
}

Entendo que a opção 1 é mais fácil de ser estendida, mas menos confortável para os usuários. Que outros problemas posso enfrentar usando uma dessas opções? Ou devo criar uma solução híbrida como:

Opção 3:

{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            },
    ... other keys
}

As chaves "some-stats-key1" e "some-stats-key2" são apenas valores internos e espera-se que o usuário da API as mapeie em nomes legíveis usando a documentação. Todas as chaves são únicas.

A ordem das "estatísticas" não é importante.

O caso de uso típico é apenas para obter todas as estatísticas, combinar chaves com nomes legíveis e mostrar como uma tabela em uma página da web. Mas atualmente não posso dizer se ninguém precisará apenas de uma parte das estatísticas posteriormente.

Existe uma prática recomendada para esse problema?

Eu optaria pela opção 2. Se o consumidor da API se converter some-stats-key1em algo legível, isso provavelmente significa que ele / ela tem uma lista de valores nos quais está interessado (digamos some-stats-key1e some-stats-key3) e iterará sobre essa lista. Ao escolher um objeto JSON, ele será desserializado como um dicionário / mapa que fornece uma consulta conveniente para o consumidor da API.

Isso será mais complicado com a opção 1, onde o consumidor precisa iterar sobre a matriz JSON ou pré-criar seu próprio dicionário com chaves interessantes.

A opção 3 é um pouco detalhada demais para mim, a duplicação dos nomes das chaves simplesmente não me agrada.

Se a extensibilidade for uma preocupação, você sempre poderá publicar uma v2 da sua API retornando algo como

"stats": {
    "some-stats-key1": { "value": 10, "error-margin": 0.1 },
    "some-stats-key2": { "value": 20, "error-margin": 0.2 }
}

e mantenha a v1 para compatibilidade com versões anteriores. Manter a compatibilidade com versões anteriores em uma única versão da API pode ser uma PITA real, se você não tiver controle completo sobre como a API é consumida. Vi um consumo de uma API da minha 'quebra' quando adicionei um par de valor-chave extra (opcional) (ou seja, não alterei a estrutura).

As duas opções têm as vantagens clássicas da Lista versus Mapa.

1) A lista permite entradas duplicadas e mantém a ordem. Se esses recursos forem importantes, use a Lista, mesmo que seja mais desajeitada.

2) O mapa não permite duplicatas. A manutenção da ordem é possível com um pouco de trabalho extra. A grande vantagem é mais simplicidade no formato dos dados, e a busca por um elemento específico é trivial.

Minha escolha padrão é sempre o mapa mais simples, mas YMMV.

Quando obtenho dados de uma API, sempre verifico se tudo está como eu esperava. Portanto, meu esforço para processar seus dados consiste na verificação e no processamento real.

No caso 1, tenho que verificar: a. Existe uma matriz. b. Todos os itens da matriz são dicionários. c. Todo dicionário tem uma chave "nome". d. Todos os valores para a chave "nome" são exclusivos.

No caso 3, tenho que verificar: a. Existe um dicionário. b. Todos os valores no dicionário são dicionários. c. Cada dicionário possui uma chave "nome" com um valor que corresponde à chave no dicionário externo. Um pouco melhor.

No caso 2, tenho que verificar: a. Existe um dicionário.

(Claro que tenho que verificar os valores também). Portanto, o seu caso 2 requer a menor quantidade de verificação do meu lado. Na verdade, recebo uma estrutura de dados que é imediatamente utilizável.

O único problema com 2 é que não é extensível. Portanto, em vez de enviar o valor como um número, você pode enviar {value: 10}, que pode ser estendido de forma compatível com versões anteriores.

Redundância é ruim. A única coisa que a redundância atinge é me fazer escrever mais código e me forçar a pensar no que devo fazer se os bits redundantes não concordarem. A versão 2 não possui redundância.

Desde que você solicitou boas práticas para o design da API:

• Eu nunca retorno uma resposta da API contendo um objeto no nível superior. Todas as chamadas de serviço retornam um conjunto (como uma matriz) e esse conjunto contém elementos (como instâncias do objeto). O número de objetos retornados na matriz é irrelevante para o servidor. Se o cliente precisar determinar o número de itens retornados na resposta, essa carga será imposta pelo cliente. Se um único item for esperado, ele será retornado como um conjunto de unidades
• Quando estou projetando uma API, não pretendo saber qual tecnologia específica meus clientes de API usarão para consumir a API, mesmo quando eu sei qual tecnologia específica eles provavelmente usarão. Minha responsabilidade é comunicar minhas representações de domínio de forma consistente a todos os consumidores, não de forma conveniente a um consumidor específico.
• Se existe uma opção estrutural para permitir que a resposta seja composta, essa estrutura tem prioridade sobre as opções que não
• Esforço-me para evitar criar representações que tenham estruturas imprevisíveis.
• Se a estrutura de uma representação puder ser prevista, todas as instâncias dentro do conjunto de respostas deverão ter a mesma representação e o conjunto de respostas deverá ser consistente internamente.

Portanto, dadas as estruturas que você propôs, a estrutura que eu implementaria seria semelhante a esta

[
   { /* returns only the 'common' metrics */
      "stats": [
                  {"key":"some-metric1","value":10},
                  {"key":"some-metric2","value":20}
               ]
   },
   { /* returns an optional metric in addition to the "common" metrics */
      "stats": [
                  {"key":"some-metric1","value":15},
                  {"key":"some-metric2","value":5},
                  {"key":"some-optional-metric", "value":42}
               ]
   },
   { /*returns the 'common' metrics as well as 2 candidates for "foo-bar" */
      "stats": [
                  {"key":"some-metric1", "value": 5},
                  {"key":"some-metric2", "value": 10},
                  {"key":"foo-bar-candidate", "value": 7},
                  {"key":"foo-bar-candidate", "value": 11}
               ]
   }
]