JSON es un formato de texto ligero que sirve para representar datos estructurados y es el estándar dominante para intercambiar información en las APIs REST.
El día que Liverpool necesitó hablar con su bodega
Imagina que son las 11 de la noche del Buen Fin. Daniela, desarrolladora en Liverpool, recibe una alerta. La aplicación móvil no puede mostrar el inventario en tiempo real. Miles de compradores ven productos "disponibles" que ya no existen en bodega.
El problema no era el servidor. Era el formato. El sistema de bodega enviaba datos en un lenguaje que la app no entendía. Daniela necesitaba un traductor universal entre dos máquinas completamente distintas.
Ese traductor existe desde 2001. Se llama JSON, y hoy mueve más del 70% de los datos que circulan por las APIs del mundo.
El idioma que todas las máquinas entienden
JSON significa JavaScript Object Notation. Aunque nació del lenguaje JavaScript, hoy lo usan Python, Java, PHP, Swift, Kotlin y prácticamente cualquier lenguaje moderno. Es texto plano, no binario. Cualquier humano puede leerlo sin herramienta especial.
La idea central es simple: los datos se organizan en pares de clave y valor. La clave describe qué es el dato. El valor es el dato en sí.
Así luce un producto de Mercado Libre representado en JSON:
{
"id": 48291,
"nombre": "Laptop Lenovo IdeaPad 3",
"precio": 12500,
"disponible": true,
"categoria": "Electrónica"
}
Las llaves {} envuelven el objeto. Cada clave va entre comillas dobles. El valor puede ser un número, texto, booleano (true o false), o incluso otro objeto.
Los cinco tipos de valores en JSON
Entender los tipos de valores es lo más importante para leer y escribir JSON sin errores.
El primer tipo es el texto (string). Siempre va entre comillas dobles. Por ejemplo: "nombre": "Bimbo Pan Blanco".
El segundo tipo es el número (number). No lleva comillas ni símbolo de moneda. Escribes el valor puro: "precio": 18500. Nota que en tu código fuente usas el número crudo, pero cuando lo presentas al usuario lo formateas como $18,500.
El tercer tipo es el booleano (boolean). Solo tiene dos valores posibles: true o false. Sin comillas. Por ejemplo: "activo": true.
El cuarto tipo es el arreglo (array). Es una lista de valores encerrada en corchetes []. Muy útil para devolver colecciones.
El quinto tipo es el objeto anidado (nested object). Un objeto dentro de otro objeto. Perfecto para representar relaciones complejas.
Aquí un ejemplo que combina los cinco tipos. Este es el JSON que devolvería la API de FEMSA para un pedido de su plataforma de distribución:
{
"pedido_id": 10923,
"cliente": "Tienda La Esperanza",
"total": 4750,
"enviado": false,
"productos": [
{
"nombre": "Coca-Cola 600ml",
"cantidad": 48,
"precio_unitario": 14
},
{
"nombre": "Agua Ciel 1L",
"cantidad": 24,
"precio_unitario": 10
}
],
"direccion": {
"calle": "Av. Insurgentes Sur 1234",
"ciudad": "Ciudad de México",
"cp": "06600"
}
}
Fíjate en la clave "productos". Su valor es un arreglo [] con dos objetos {} adentro. Eso es JSON anidado. Es normal y muy poderoso.
Cómo fluye JSON en una API REST
Cuando tu aplicación hace una petición GET a /v1/productos/48291, el servidor responde con un JSON como el del primer ejemplo. Tu app recibe ese texto, lo convierte en un objeto de su lenguaje (proceso llamado parsing o deserialización), y ya puede trabajar con los datos.
Cuando envías datos al servidor, el proceso es al revés. Tu app toma un objeto local, lo convierte en texto JSON (proceso llamado serialización), y lo manda en el cuerpo del request. Por eso en los headers de tu petición siempre vas a ver:
Content-Type: application/json
Ese header le avisa al servidor: "lo que te mando está en formato JSON". Sin ese header, el servidor puede rechazar tu petición o interpretarla mal.
JSON en acción: registrar un producto en Liverpool
Supón que eres parte del equipo que construye la API interna de Liverpool. Quieres registrar un nuevo producto. Haces un POST a /v1/productos y en el cuerpo del request mandas:
{
"nombre": "Cafetera Oster Digital",
"precio": 1299,
"stock": 150,
"categoria": "Hogar",
"disponible": true
}
El servidor procesa el JSON, guarda el producto en la base de datos, y te responde con el nuevo recurso creado, ahora con su identificador único:
{
"id": 90847,
"nombre": "Cafetera Oster Digital",
"precio": 1299,
"stock": 150,
"categoria": "Hogar",
"disponible": true,
"creado_en": "2024-11-15T23:14:00Z"
}
Observa que el servidor devuelve más información de la que recibió. Agregó "id" y "creado_en". Así es el flujo típico de un POST exitoso.
Errores comunes al escribir JSON
El error más frecuente entre personas que están aprendiendo es olvidar las comillas en las claves. En JSON, todas las claves deben ir entre comillas dobles. Esto está mal:
{
nombre: "Bimbo Donas",
precio: 35
}
Y esto está bien:
{
"nombre": "Bimbo Donas",
"precio": 35
}
El segundo error común es la coma final (trailing comma). En JSON no puedes dejar una coma después del último elemento. Este ejemplo causa un error de parseo:
{
"nombre": "Bimbo Donas",
"precio": 35,
}
La coma después de 35 rompe el JSON. Elimínala.
El tercer error es mezclar tipos sin intención. Si "precio" debe ser un número para hacer cálculos, no lo escribas como texto: "precio": "1299". Esa versión entre comillas es una cadena de texto, no un número. Tu código no podrá multiplicarla ni sumarla directamente.
Una forma rápida de validar tu JSON antes de mandarlo es usar un validador en línea como jsonlint.com. Pega tu JSON ahí y te indica si tiene errores de sintaxis.
Por qué JSON ganó la batalla de los formatos
Antes de JSON dominaba XML. Un producto simple en XML se veía así:
<producto>
<nombre>Laptop Lenovo IdeaPad 3</nombre>
<precio>12500</precio>
<disponible>true</disponible>
</producto>
El mismo producto en JSON ocupa un 30% menos de espacio en promedio. Menos espacio significa transferencia más rápida y menor costo de ancho de banda, especialmente importante cuando tu API maneja millones de peticiones diarias como las de Mercado Libre.
Adicionalmente, JSON es nativo en JavaScript, el lenguaje del navegador. Eso significa que una app web puede procesar una respuesta JSON con código mínimo, sin librerías adicionales.
El cierre del Buen Fin
Daniela resolvió el problema de Liverpool esa noche. El sistema de bodega exportaba datos en XML. La app esperaba JSON. La solución fue agregar una capa de transformación en el servidor que convertía el XML de bodega a JSON antes de enviarlo a la app.
A las 11:47 de la noche, el inventario volvió a mostrarse en tiempo real. Los compradores pudieron ver exactamente qué había disponible. Daniela aprendió esa noche algo que no está en ningún manual: el formato de los datos importa tanto como los datos mismos.
JSON no es magia. Es un acuerdo. Un acuerdo que casi todo el internet firmó, y por eso funciona.