Padrões: lista vs objeto

APIs e arquivos de config escolhem formas de nível superior diferentes. Reconhecer padrões ajuda a ler documentação mais rápido e a desenhar endpoints consistentes.

Array na raiz

JSON válido pode ser um array no topo:

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

Comum para listas estáticas pequenas ou export em lote. Muitas APIs REST preferem um wrapper de objeto para metadata ter onde ficar.

Objeto envelope

Envolva dados de lista mais metadata:

{
  "data": [
    {"id": 1, "name": "Alpha"}
  ],
  "meta": { "total": 42, "page": 1 }
}

Nomes variam (data, items, results, records). A ideia é a mesma: payload + contexto em um objeto.

Campos de paginação

Padrões repetidos:

{
  "items": [],
  "nextCursor": "abc123",
  "hasMore": true
}

ou estilo offset com page, pageSize, totalCount. Clientes não devem assumir nomes de campos — leia a spec de cada API.

Documentos só com objeto

Configuração costuma ser um único objeto:

{
  "theme": "dark",
  "features": { "beta": false }
}

Sem array na raiz; objetos aninhados agrupam configurações.

Escolhendo uma forma

Prefira raiz objeto quando	Array na raiz OK quando
Precisa de paginação ou erros junto com dados	Catálogo pequeno e fixo
Versionamento ou objetos links aparecem	Ferramentas internas, fixtures
Vários tipos de recurso compartilham um endpoint	Feeds públicos de dados simples

Consistência dentro da sua própria API importa mais do que copiar nomes de campos de outro produto.