Qué es una API — las reglas acordadas entre programas para intercambiar datos, y JSON

Este artículo trata las API.

Una API son las reglas acordadas con las que los programas intercambian datos entre sí.

Veremos las tres partes de una llamada y JSON, el formato de texto que vuelve.

• Qué envía en realidad «llamar a una API», y adónde
• Las tres partes de una llamada — URL, método y respuesta
• Cómo leer las claves y los valores del JSON que vuelve
• El código de estado que indica si hubo éxito o fallo, y qué hacer con cada número

«Llamar a una API» es enviar una solicitud a una URL determinada y recibir una respuesta

Los datos del tiempo no los tiene tu propio programa, sino el servidor de un servicio externo.

La API que se llama con solicitudes y respuestas HTTP es una Web API, y cada una de las URL que acepta es un endpoint.

Tanto un servicio externo como el servidor de my-app pueden ser el lado que provee.

Y una sola pantalla tampoco llama necesariamente a un único endpoint.

Antes de que aparezca la página se producen tres idas y vueltas de solicitud y respuesta.

Lo único a lo que el navegador se conecta directamente es al servidor de my-app.

Ese mismo servidor es quien provee visto desde el navegador, y quien llama visto desde la API del tiempo.

Llamar a una API es enviar y recibir

Llamar a una API es enviar una solicitud a una URL determinada y recibir la respuesta que vuelve.

Cada una de esas URL es un endpoint; quien llama puede ser el navegador o tu propio servidor, y quien provee tampoco es necesariamente un servicio externo.

Las tres partes de una llamada — URL, método y respuesta

En las instrucciones y en la documentación solo se escriben tres cosas.

Adónde se envía (URL), qué quieres hacer (método) y qué vuelve (respuesta).

La primera, la URL, reparte su papel entre lo que va antes del ? y lo que va después.

Lo que va detrás del ? es un parámetro (query parameter; una condición de los datos que quieres, puesta al final de la URL con la forma nombre=valor), también llamado parámetro de consulta.

La segunda parte es el método (HTTP method; una palabra fijada, como GET o POST, que indica qué quieres hacer con la solicitud).

Se escribe al principio de la línea y cambia el comportamiento aunque envíes a la misma URL.

GET no cambia los datos del otro lado, pero POST los cambia en el momento en que se envía.

En las instrucciones aparece escrito con el método y la URL uno detrás del otro.

Las líneas que empiezan por # son la explicación, y la línea de debajo de cada una es cómo se llama.

# Obtener el tiempo. Primero el método, después la URL (al final, los parámetros)
GET https://api.example.com/weather?city=tokyo

# Registrar una reserva. Misma URL, distinto método, distinto comportamiento
POST https://example.com/reservations

El documento que reúne cómo se llama y la forma de la respuesta que vuelve es la documentación de la API (API reference).

Cuando las instrucciones dicen «consulta la documentación de la API», es ahí donde buscas las tres partes.

Antes de enviar solo decides dos cosas

Antes de enviar solo decides dos cosas: adónde lo envías y qué quieres hacer.

Adónde lo envías es la URL, y la parte anterior al ? es el endpoint; qué quieres hacer es el método. La tercera parte, la respuesta, es la única que no decides tú: lees lo que vuelve.

JSON es un formato de texto que describe los datos con pares de clave y valor

El «JSON que ha vuelto» de las instrucciones es el cuerpo de la respuesta.

JSON (JavaScript Object Notation; un formato hecho solo de texto que describe los datos con pares de clave y valor) es el formato más habitual para el cuerpo de las Web API.

El JSON que devuelve la API del tiempo tiene esta forma.

{
  "city": "Tokyo",
  "temp": 23.5,
  "rain": false,
  "forecast": [
    { "day": "mon", "high": 25 },
    { "day": "tue", "high": 22 }
  ]
}

Lo que hay en la lista son pares de clave y valor (key / value; la clave es el nombre puesto a un valor, y el valor es el contenido al que apunta ese nombre).

En "temp": 23.5, temp es la clave y 23.5 es el valor; la clave y el valor se unen con : y los pares se separan con ,.

Dentro de { } se listan los pares, y a veces ese valor es a su vez un [ ] o un { }.

El cuarto valor es un array (varios valores puestos en orden dentro de [ ]) y cada elemento va otra vez entre { }.

{ } y [ ] se pueden anidar en tantos niveles como haga falta.

Para sacar un elemento de un array lo señalas por número, como [0], y la numeración empieza en 0, no en 1.

Los valores que no son [ ] ni { } se escriben de tres formas, y se distinguen por si llevan " " o no.

Tal como llega, el cuerpo es una única cadena larga, así que indicar una clave no te da el valor.

En los libros de iniciación primero lo conviertes, con una línea como JSON.parse, en algo cuyas claves se pueden leer, y luego señalas el valor por el nombre de la clave, como data.city.

Solo en la última fila la clave está mal escrita a propósito, por un carácter.

Una clave mal escrita no da ningún error, así que, cuando obtengas undefined, lo primero es comparar cómo está escrita con el JSON.

El nombre lleva JavaScript dentro, pero se usa en las respuestas de las API porque cualquier lenguaje puede leerlo y escribirlo.

JSON solo son pares de nombre y contenido

JSON no es más que una secuencia de texto que lista pares formados por un nombre y su contenido.

El nombre es la clave y el contenido es el valor; tal como llega es una única cadena larga, así que lo conviertes en algo legible por clave antes de sacar los valores.

La respuesta no siempre es un éxito — el código de estado decide qué haces

La API del tiempo funciona fuera de tu propio programa, así que la llamada puede fallar.

Por eso la respuesta no llega solo con el cuerpo.

Mira por partes lo que vuelve.

Las tres cifras del principio son el código de estado (status code; el número que indica si hubo éxito o fallo y de qué tipo).

Mira primero el número y lee las claves del cuerpo solo cuando hay éxito.

No hay que memorizar las tres cifras: la primera cifra decide qué haces después.

Aun con la misma API del tiempo, el número que vuelve cambia según lo que enviaste y según el estado de quien provee.

Además del 404, cuando ocurre un fallo en el lado que provee vuelve un 500.

404 no es solo el número de «esta página no existe»: en una API también vuelve cuando no hay datos que cumplan las condiciones del parámetro.

Si llamas siguiendo las instrucciones y vuelve un 404, compara la escritura y los parámetros con la documentación de la API.

Entre los números que empiezan por 4, el 401 es el de cuando no hay nada que indique quién llama, o lo que hay no es correcto.

Lo que se añade a la solicitud para indicarlo es la clave de API.

Mira el número antes de leer el cuerpo

Cuando vuelve una respuesta, mira el número antes de leer el cuerpo.

Si empieza por 2, el cuerpo lleva la clave que quieres; si empieza por 4, corrige la URL y las condiciones que enviaste; si empieza por 5, espera un poco y vuelve a llamar.