Patrones de documento: lista frente a objeto

APIs y archivos de config eligen distintas formas de nivel superior. Reconocer patrones ayuda a leer documentación más rápido y diseñar endpoints consistentes.

Array raíz

JSON válido puede ser un array en la raíz:

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

Común en listas estáticas pequeñas o exportaciones por lotes. Muchas APIs REST prefieren un objeto envoltorio para que la metadata tenga sitio.

Objeto envoltorio

Envuelve datos de lista más metadata:

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

Los nombres varían (data, items, results, records). La idea es la misma: payload + contexto en un objeto.

Campos de paginación

Patrones repetidos:

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

o estilo offset con page, pageSize, totalCount. Los clientes no deben asumir nombres de campo: lee la spec de cada API.

Documentos solo objeto

La configuración suele ser un solo objeto:

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

Sin array en la raíz; objetos anidados agrupan ajustes.

Elegir una forma

Prefiere raíz objeto cuando	Array raíz OK cuando
Necesitas paginación o errores junto a datos	Catálogo pequeño y fijo
Aparecen objetos de versión o links	Herramientas internas, fixtures
Varios tipos de recurso comparten un endpoint	Feeds públicos de datos simples

La consistencia dentro de tu propia API importa más que copiar nombres de campo de otro producto.