Llamar a una API desde tu código

Necesitas el tiempo de mañana en tu programa. Abres la documentación de la API en una pestaña del navegador, pegas la dirección y ves una preciosa página de JSON. Funciona. Así que copias esa dirección en tu código, lo ejecutas, y el programa se cae con un muro de texto. En la API no ha cambiado nada entre esos dos momentos. Lo que ha cambiado es quién preguntaba.

GET /v1/weather?city=Berlin HTTP/1.1
Host: api.example.org
Accept: application/json


HTTP/1.1 200 OK
Content-Type: application/json

{"city": "Berlin", "tempC": 14}

req:
  GET /v1/weather?city=Berlin

res:
  status = 200
  body.tempC = 14

if (status != 200) -> error
body.tempC

Tu navegador es un programa que hace en silencio mucho trabajo extra por ti. Guarda cookies para que sigas con la sesión iniciada. Sigue las redirecciones y te enseña la página final sin mencionar los tres saltos del camino. Reintenta cuando se corta la conexión. Ejecuta el JavaScript sin el cual una web moderna no muestra nada. Y cuando recibe un 404, dibuja alegremente una bonita página de error, así que la petición parece haber salido bien. Tu programa no hace nada de eso salvo que lo escribas tú. Un código 404 no es una página de error para tu código: es un número que tienes que comprobar, y si no lo compruebas, intentarás leer datos del tiempo dentro de un mensaje de error.

Hay otra familia que vas a ver constantemente en código real: 3xx. Una redirección es el servidor diciendo «aquí no, mira allí». El navegador la sigue por ti y ni te enteras. Puede que tu cliente HTTP la siga o puede que no, según cómo esté configurado, y la respuesta cambia qué datos acabas teniendo.

Un tiempo de espera dice: voy a esperar esto por una respuesta, y luego paro y lo trato como un fallo. Sin él, tu programa espera para siempre a un servidor que nunca va a responder: el botón gira, la petición no acaba nunca y el usuario no tiene ni idea de qué está pasando. Dos segundos es una elección normal para una petición que está esperando una persona. La consecuencia importante es que un tiempo de espera no demuestra que la petición no ocurriera: puede que el otro lado la recibiera e hiciera el trabajo, y que solo se perdiera la respuesta de vuelta.

Así que un flujo de pago sensato es este: dale a cada intento una clave única, envíala con la petición y ponle un tiempo de espera. Si la petición agota el tiempo, vuelve a enviarla con la misma clave. Si el dinero ya se movió, el otro lado reconoce la clave y te lo dice en lugar de cobrar otra vez. Y nunca reintentas sin fin: un par de intentos con pausas cada vez más largas, luego te rindes y se lo dices al usuario con honestidad.