JSON es el formato en el que vamos a encontrarnos la mayoría de respuestas cuando realicemos una llamada a una API. Si quieres repasar qué es una API y cómo nos puede ayudar a diseñar, te recomiendo echar un ojo a este artículo.

Una de las ventajas que tiene JSON frente a otros formatos como XML es que es mucho más fácil de leer ya que tiene estructura mínima, cediendo todo el protagonismo al contenido.

Una estructura sencilla en JSON tiene este aspecto:

{
   "dni": "12345678A",
   "nombre": "Maria",
   "apellido1": "Rodríguez",
   "apellido2": "Martín",
   "edad": 12,
   "notaMedia": 7.8
}

Como puedes ver, contiene los datos básicos de una persona: su DNI, nombre, dos apellidos, su edad y su nota media. Con este JSON tan sencillo ya podríamos sacar información valiosa a la hora de diseñar. Además de la información disponible, el JSON nos revela que se pueden mostrar y editar en campos diferentes el nombre y los apellidos. Algo que no podríamos hacer si estos viniesen dados en una sola cadena de texto, puesto que no tendríamos forma de saber que parte corresponde al nombre y que parte corresponde a cada apellido.

Los básicos de JSON

Hablemos un poco de la sintaxis. Las llaves de apertura y cierre ({}) son las que marcan el inicio y el fin de la estructura, mientras que la coma (,) sirve para separar los diferentes elementos que contienen la información.

Cada elemento del JSON esta construido de la siguiente forma:

«clave» : valor

La clave es una cadena de texto que no trae información de la base de datos o el backend, sino que nos ayuda a hacer el JSON más legible entendiendo a qué hace referencia el valor. Si alguna vez construyes un JSON piensa que, cuanto más exacta sea la descripción, más fácil será para la persona tenga que consumirlo entender para lo que sirve cada campo. ¿Te imaginas interpretar JSON más complejos sin más información que la que da la propia estructura? Por favor, nunca hagas algo como esto 😉

{
   "aaaa": "12345678A",
   "bbbb": "Maria",
   "cccc": "Rodríguez",
   "dddd": "Martín",
   "eeee": 12,
   "ffff": 7.8
}

La segunda parte del elemento es el valor. Aquí podríamos diferenciar entre valores simples (cadenas de texto, números, valores booleanos, fechas…) o complejos (listas y estructuras).

En el ejemplo que hemos visto hay varios tipos de valores simples: cadena de texto, número entero y número decimal, donde para separar la parte entera de la decimal se usa el punto (.).

Las cadenas de texto siempre van entre comillas («») y con ellas se representan la mayoría de los valores, excepto algunos como números y valores booleanos (true/false). Un caso particular de cadenas de texto son las fechas, para las que se suele usar el formato ISO 8601, que tiene el siguiente aspecto:

2020-08-14T10:05:43.511Z

La ventaja que tiene usar este formato es que la mayoría de lenguajes de programación son capaces de crear un objeto con la fecha y hora a partir de la cadena de texto. A partir de ahí podríamos especificar el formato en el que queremos que se muestre de forma muy sencilla (por ejemplo «dd-mm-yyyy») o realizar operaciones (tiempo desde, tiempo hasta…) y comparaciones entre dos objetos que contengan una fecha.

Para cerrar el bloque de los valores simples, aquí tienes un ejemplo de JSON que contiene los formatos más comunes:

{
   "ejemploTexto": "texto que puede ser todo lo largo que queramos",
   "ejemploEntero": 4,
   "ejemploDecimal": 3.9,
   "ejemploBooleano": false,
   "ejemploFecha": "2020-08-14T10:05:43.511Z"
}

Un pasito más

Es habitual que en cuanto el conjunto de datos que obtenemos sea un poco complejo nos encontremos también con estructuras y listas.

Por continuar con la temática académica, supongamos que tenemos almacenados los datos de las asignaturas de un centro (nombre, curso, itinerario y datos del profesor) y una llamada a la API que nos da el detalle de una asignatura en concreto (indicando su id al hacer la llamada). El JSON de respuesta podría ser algo así:

{
   "id": "BACH-1-MATEMATICAS",
   "nombre": "Matemáticas",
   "curso": "1º de Bachillerato",
   "itinerario": "Científico - Técnico",
   "profe": {
      "nombre": "Laura",
      "apellido1": "García",
      "apellido2": "López"
   }
}

Como vemos en el ejemplo, el valor para el campo «profe» no es una cadena de texto ni un número entero sino otra estructura JSON. Esto nos permite crear niveles jerárquicos dentro de la estructura principal manteniendo los datos ordenados, de forma que tenemos diferentes elementos para la información que queremos representar («nombre», «apellido1» y «apellido2») pero todos ellos pertenecen a un campo «profe».

La sintaxis es exactamente la misma. Presta atención a las llaves de apertura y cierre ({}), que serán las que te indiquen dónde acaba esta «subestructura» y volvemos a la superior. Otra pista es fijarse en el indentado o tabulado (alineación vertical de los elementos). Esto se ve mejor con un ejemplo:

Hemos añadido una tercera estructura JSON anidada que representa los campos de la dirección. Gracias a la sintaxis y al tabulado (reforzado en la imagen con las líneas rojas) es más facil visualizar que la estructura formada por los campos «calle», «numero» y «cpostal» es el valor para la clave «dirección», que junto a los campos «nombre», «apellido1» y «apellido2» conforman la estructura asignada como valor al campo «profe».

Como puedes ver, con una estructura JSON ordenada es muy fácil ver la jerarquía y los elementos que conforman cada nivel. Si por lo que sea te encuentras con una estructura desordenada puedes pegarla en herramientas como JSONLint, que la formatearán correctamente.

Lo último que vamos a ver en este artículo son las listas. El uso de listas nos permite asignar a una clave un conjunto de valores del mismo tipo (no diría que es obligatorio, pero yo nunca me he encontrado con un caso en el que sean diferentes). De nuevo, los valores pueden ir de lo más simple (cadenas de texto, números…) a lo más complejo (estructuras o listas anidadas).

Sintácticamente una lista se abre y cierra con corchetes ([]) y los elementos se separan usando la coma (,). Vamos a ver un par de ejemplos para entenderlo mejor: supongamos que para una asignatura podemos obtener un listado de los alumnos. La forma más sencilla de hacerlo sería con una lista de cadenas de texto:

{
   "id": "BACH-1-MATEMATICAS",
   "alumnos":[
      "Marta López",
      "Jorge Martínez",
      "Beatriz García"
   ]
}

Para hacerlo un poco más complejo, recuperamos la primera estructura, en la que almacenábamos más datos de cada alumno (DNI, nombre y apellidos, edad y nota media) y vamos a proporcionar un listado de estructuras JSON en el que cada una contiene los datos de un alumno:

{
   "id": "BACH-1-MATEMATICAS",
   "alumnos": [
      {
         "dni": "12345678A",
         "nombre": "Marta",
         "apellido1": "López",
         "apellido2": "Martín",
         "edad": 12,
         "notaMedia": 7.8
      },
      {
         "dni": "12345678B",
         "nombre": "Jorge",
         "apellido1": "Martínez",
         "apellido2": "González",
         "edad": 11,
         "notaMedia": 8.1
      },
      {
         "dni": "12345678A",
         "nombre": "Beatriz",
         "apellido1": "García",
         "apellido2": "Gómez",
         "edad": 12,
         "notaMedia": 9.3
      }
   ]
}

Con esto hemos dado un buen repaso a los conceptos básicos sobre JSON y podrás entender la gran mayoría de respuestas de las APIs con las que quieras trabajar. Normalmente la documentación de la propia API te proporcionará información sobre los campos para que puedas entender mejor que información tienes en cada uno. No obstante te he dejado abajo del todo algunas referencias y recursos con los que puedes ampliar conocimientos, entre ellos la documentación oficial de JSON.

Chuleta con los básicos de JSON

Como resumen te dejo por aquí los caracteres importantes dentro de una estructura JSON que hemos ido viendo a lo largo del artículo:

• Llaves ({}) – Marcan el inicio y final de una estructura JSON.
• Corchetes ([]) – Marcan el inicio y final de una lista.
• Coma (,) – Separa elementos en una estructura o en un listado.
• Comillas («») – Marcan el inicio y el final de una cadena de texto.
• Dos puntos (:) – Separan clave y valor en cada elemento de la estructura.
• Punto (.) – Separa la parte entera de la decimal en un número.

Y para que tengas un ejemplo completo, esta estructura podría ser el detalle de una asignatura, algo más larga que las anteriores pero con ejemplos de todos los conceptos que hemos ido aprendiendo:

{
   "id": "BACH-1-MATEMATICAS",
   "nombre": "Matemáticas",
   "curso": "1º de Bachillerato",
   "itinerario": "Científico - Técnico",
   "profe": {
      "dni": "00000000A",
      "nombre": "Laura",
      "apellido1": "García",
      "apellido2": "López",
      "direccion": {
         "calle": "Cerezo",
         "numero": 17,
         "cpostal": 28017
      }
   },
   "alumnos": [
      {
         "dni": "12345678A",
         "nombre": "Marta",
         "apellido1": "López",
         "apellido2": "Martín",
         "edad": 12,
         "notaMedia": 7.8
      },
      {
         "dni": "12345678B",
         "nombre": "Jorge",
         "apellido1": "Martínez",
         "apellido2": "González",
         "edad": 11,
         "notaMedia": 8.1
      },
      {
         "dni": "12345678A",
         "nombre": "Beatriz",
         "apellido1": "García",
         "apellido2": "Gómez",
         "edad": 12,
         "notaMedia": 9.3
      }
   ]
}

Ahora es el momento de practicar. Puedes hacerlo de dos maneras:

1. Construyendo estructuras JSON. Para este artículo yo me he inventado estructuras a partir de un conjunto de datos que podría tener una API. Haz lo mismo e inventa ejemplos de JSON que mapeen modelos de datos ficticios o que conozcas. Para «corregirlo» puedes usar herramientas como JSONLint que validan que la sintaxis de la estructura es correcta (es el que uso yo pero hay un montón más, usa el que te de más información para aprender).
   
2. Leer estructuras ya existentes. En el siguiente artículo te enseñaré como hacerlo con Postman, pero de momento puedes consultar en el Portal de datos abiertos de la CAM multitud de datasets en formato JSON. Quién sabe, ¡igual hasta te inspiran para algún pequeño proyecto!

Referencias y recursos para profundizar:

• https://www.json.org/json-en.html
• https://www.w3schools.com/js/js_json_intro.asp
• https://stackoverflow.com/questions/10286204/the-right-json-date-format

---

Este es el segundo artículo de la colección «APIs y Postman 4 Disainers«. Si quieres leer más sobre cómo las APIs nos ayudan a diseñar, te recomiendo echar un ojo al este artículo. También puedes ver algunos ejemplos de llamadas a APIs con Postman en este otro (pendiente de publicación).

¡Gracias por leerme! 🙂