Uso de JSON anidado y estructuras complejas en APIs

1 Introducción

En la vida real, los datos que manejan las aplicaciones rara vez son simples. Por ejemplo:

  • Un usuario puede tener varias direcciones.
  • Un pedido puede incluir muchos productos.
  • Un comentario puede incluir información del autor y respuestas.

👉 Para representar estas relaciones, las APIs REST usan JSON anidado y estructuras complejas.

2 JSON anidado

Un JSON anidado es aquel donde un valor de un objeto no es solo un número o texto, sino otro objeto o un arreglo de objetos.

Ejemplo básico (usuario con dirección)

{
  "id": 1,
  "nombre": "Carlos",
  "email": "carlos@ejemplo.com",
  "direccion": {
    "calle": "Av. Colón",
    "numero": 1234,
    "ciudad": "Córdoba",
    "pais": "Argentina"
  }
}

👉 Aquí el campo direccion es un objeto JSON anidado dentro del usuario.

3 Arreglos de objetos

Muchas veces un recurso está compuesto por una lista de objetos.

Ejemplo (usuario con múltiples teléfonos)

{
  "id": 1,
  "nombre": "Ana",
  "telefonos": [
    { "tipo": "móvil", "numero": "3511234567" },
    { "tipo": "fijo",  "numero": "3517654321" }
  ]
}

👉 El campo telefonos es un arreglo de objetos, cada uno con tipo y numero.

4 Ejemplo complejo en APIs REST

Supongamos una API de pedidos en un e‑commerce.

Petición (crear un pedido)

POST /pedidos
Content-Type: application/json
Accept: application/json

{
  "usuario": {
    "id": 5,
    "nombre": "Laura"
  },
  "productos": [
    { "id": 101, "nombre": "Notebook", "precio": 1500.0, "cantidad": 1 },
    { "id": 202, "nombre": "Mouse inalámbrico", "precio": 25.0, "cantidad": 2 }
  ],
  "direccion_envio": {
    "calle": "San Martín",
    "numero": 500,
    "ciudad": "Córdoba",
    "pais": "Argentina"
  },
  "estado": "pendiente"
}

Respuesta del servidor

{
  "pedido_id": 9001,
  "usuario": { "id": 5, "nombre": "Laura" },
  "productos": [
    { "id": 101, "nombre": "Notebook", "precio": 1500.0, "cantidad": 1, "subtotal": 1500.0 },
    { "id": 202, "nombre": "Mouse inalámbrico", "precio": 25.0, "cantidad": 2, "subtotal": 50.0 }
  ],
  "total": 1550.0,
  "direccion_envio": {
    "calle": "San Martín",
    "numero": 500,
    "ciudad": "Córdoba",
    "pais": "Argentina"
  },
  "estado": "pendiente",
  "fecha_creacion": "2025-09-10T12:30:00Z"
}

👉 Aquí tenemos: un objeto usuario, un arreglo de objetos productos, otro objeto direccion_envio y atributos simples como total y estado.

5 Consumo en diferentes lenguajes

A) Python

import requests  # https://requests.readthedocs.io/

resp = requests.get("https://api.ejemplo.com/pedidos/9001")
pedido = resp.json()

print("Pedido ID:", pedido["pedido_id"])
print("Usuario:", pedido["usuario"]["nombre"])
for prod in pedido["productos"]:
    print(" -", prod["nombre"], "x", prod["cantidad"], "=", prod["subtotal"])

👉 Se accede a objetos anidados con ["campo"] y a listas con for. Librería requests.

B) JavaScript

fetch("https://api.ejemplo.com/pedidos/9001") // API fetch: https://developer.mozilla.org/docs/Web/API/fetch
  .then(res => res.json())
  .then(pedido => {
    console.log("Pedido ID:", pedido.pedido_id);
    console.log("Usuario:", pedido.usuario.nombre);
    pedido.productos.forEach(p => {
      console.log(` - ${p.nombre} x${p.cantidad} = ${p.subtotal}`);
    });
  })
  .catch(err => console.error("Error:", err));

👉 En JavaScript es muy natural manejar estructuras anidadas, porque JSON proviene de JavaScript y el API fetch lo convierte fácilmente.

6 Problemas comunes con JSON anidado

  • Estructuras demasiado profundas: objetos dentro de objetos dentro de objetos → difícil de leer y procesar. Solución: dividir en recursos más simples con endpoints separados.
  • Datos repetidos: evitar duplicar información innecesaria en estructuras anidadas.
  • Errores de deserialización: si un cliente espera un objeto, pero la API devuelve un arreglo, puede fallar el parseo.

7 Buenas prácticas con estructuras complejas

  • Mantener un nivel razonable de anidación: idealmente no más de 3 niveles de profundidad.
  • Usar arreglos cuando corresponda: por ejemplo, productos debería ser siempre un arreglo, aunque tenga 1 solo elemento.
  • Estandarizar respuestas: usar la misma estructura para todas las respuestas relacionadas.
  • Documentar bien la API: un JSON complejo sin documentación genera confusión.

8 Conclusión del capítulo

Los JSON anidados permiten representar relaciones entre entidades (usuarios con direcciones, pedidos con productos, etc.). Son indispensables en APIs REST reales porque los datos del mundo real son jerárquicos y relacionados.

Es fundamental consumirlos correctamente en el cliente y mantener buenas prácticas de diseño.

👉 En resumen: JSON anidado es la forma en que REST modela la complejidad del mundo real.

Retornar