Las API, JSON y cómo trabajan juntos sistemas separados

Qué es una API

Una API (interfaz de programación de aplicaciones) es la forma definida en que una pieza de software le pide a otra que haga algo. Enumera qué se puede solicitar, qué hay que proporcionar, qué se devuelve y qué puede salir mal. La palabra importante es definida: una API es un contrato. El proveedor promete mantenerla funcionando; el consumidor promete usar solo lo que describe.

Un restaurante es la analogía habitual. La carta enumera lo que puedes pedir y lo que lleva cada plato; el camarero lleva tu pedido a la cocina y te trae el resultado. No entras en la cocina, y no necesitas saber si el chef cocina con gas o con inducción. La cocina puede cambiar su equipamiento, su personal y sus proveedores a voluntad, siempre que los platos de la carta sigan llegando tal como se describen. La carta es la API, la cocina es la implementación, y la separación entre ambas es lo que permite que las dos partes cambien de forma independiente.

Es la misma idea que las interfaces de organizar el código, aplicada a todas las escalas. También es la razón por la que a los arquitectos les importan tanto las API: una API es el punto donde el trabajo de un equipo se encuentra con el de otro, y una vez que otros dependen de ella, cambiarla es costoso.

API en proceso y API web

Algunas API se llaman dentro de un mismo programa en ejecución. Cuando un código Python llama a json.loads(text), usa la API del módulo json de la biblioteca estándar: una llamada a una función que tarda nanosegundos y solo falla si la entrada es incorrecta. Las funciones y clases públicas de una biblioteca son su API en proceso.

Una API web se llama a través de una red, normalmente con HTTP (consulta cómo se comunican las computadoras). Quien llama y el proveedor pueden estar en máquinas distintas, estar escritos en lenguajes distintos y pertenecer a organizaciones distintas. Una app de banca para dispositivos móviles se comunica con la API web del banco; los servidores del banco se comunican con la API de una red de tarjetas; una tienda se comunica con la API de un proveedor de pagos.

La diferencia no es superficial. Una llamada de red es entre miles y millones de veces más lenta que una llamada a una función, y puede fallar de formas en que no puede fallar una llamada a una función: la red pierde la solicitud, el servidor está sobrecargado, la respuesta llega después de que quien llama se haya rendido, o la solicitud tuvo éxito pero la respuesta se perdió, de modo que quien llama no puede saber si el pago se realizó. Gran parte del diseño de sistemas distribuidos, que se trata en el Capítulo 6, consiste en convivir con estos fallos.

REST: recursos, URL y verbos

La mayoría de las API web actuales siguen el estilo llamado REST (Representational State Transfer), descrito por Roy Fielding en su tesis doctoral de 2000. Fielding definió REST como un conjunto de restricciones para grandes sistemas en red como la web; en el uso cotidiano, "una API REST" significa algo más sencillo: una API HTTP organizada en torno a recursos.

Un recurso es algo que la API expone: un cliente, un pedido, un pronóstico. Cada uno tiene una URL, como /orders/1042. Una colección de ellos también tiene una URL, como /orders. El cliente actúa sobre los recursos con los métodos HTTP estándar, lee el código de estado del resultado e intercambia datos en el cuerpo, normalmente como JSON. Por tanto, los mismos pocos verbos sirven para cualquier recurso, lo que hace que las API REST bien diseñadas sean predecibles.

Los códigos de estado transmiten un significado según el cual puede actuar un programa cliente. Un código 4xx dice que el cliente ha hecho algo mal: 400 para una solicitud mal formada, 401 cuando faltan las credenciales o no son válidas, 403 cuando se sabe quién llama pero no tiene permiso, 404 cuando el recurso no existe, 429 cuando ha enviado demasiadas solicitudes. Un código 5xx dice que el servidor ha fallado: 500 para un error inesperado, 503 cuando no está disponible temporalmente. La distinción importa porque reintentar sin cambios una solicitud 4xx volverá a fallar, mientras que reintentar un 503 un poco más tarde puede tener éxito.

Los datos viajan como JSON (JavaScript Object Notation), un formato de texto normalizado como RFC 8259. Tiene solo unos pocos elementos básicos: objetos (pares nombre-valor entre llaves), arrays (listas entre corchetes), cadenas entre comillas dobles, números, true, false y null. A pesar del nombre, todos los lenguajes habituales pueden leerlo y escribirlo, y por eso se convirtió en la lengua común de las API web. Existen otros estilos que responden a necesidades distintas: GraphQL permite al cliente especificar exactamente qué campos quiere, y gRPC usa un formato binario compacto para llamadas rápidas entre servicios; el Capítulo 6 los compara.

GET /v1/forecast?city=Kigali&days=2 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_test_4f9a...
Accept: application/json

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

{
  "city": "Kigali",
  "units": "metric",
  "days": [
    {"date": "2026-10-23", "min_c": 16, "max_c": 27, "rain_chance": 0.6},
    {"date": "2026-10-24", "min_c": 16, "max_c": 26, "rain_chance": 0.4}
  ]
}

import os
import requests

API_KEY = os.environ["WEATHER_API_KEY"]   # never hard-code secrets

resp = requests.get(
    "https://api.example.com/v1/forecast",
    params={"city": "Kigali", "days": 2},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=3,                 # give up after 3 seconds
)
resp.raise_for_status()        # raises an error for 4xx and 5xx
tomorrow = resp.json()["days"][0]
print(tomorrow["max_c"], "degrees, rain chance", tomorrow["rain_chance"])

¿Quién llama? Claves de API y tokens

La mayoría de las API necesitan saber quién llama, para facturarle, limitarle y decidir qué puede ver. Conviene separar dos ideas desde el principio. La autenticación responde a "¿quién eres?"; la autorización responde a "¿qué tienes permitido hacer?"

Una clave de API es una cadena secreta larga que identifica a la aplicación que llama y se envía con cada solicitud, normalmente en una cabecera. Es sencilla, e identifica a un programa en lugar de a una persona. Un token de acceso es una credencial de corta duración que se emite después de que alguien inicia sesión, a menudo en nombre de un usuario concreto y con permisos concretos ("leer el calendario de este usuario, pero no su correo electrónico"); normalmente se envía como Authorization: Bearer <token>. Los tokens caducan, así que uno robado solo es útil durante un tiempo limitado. Los protocolos estándar que hay detrás, OAuth 2.0 y OpenID Connect, se tratan en identidad y acceso.

Se use lo que se use, las reglas son las mismas: envía las credenciales solo por HTTPS, mantenlas fuera del código fuente y de las apps para dispositivos móviles, de donde cualquiera puede extraerlas, guárdalas en un gestor de secretos o en la configuración del entorno, y asegúrate de poder revocarlas y sustituirlas rápidamente.

Webhooks: la API te devuelve la llamada

A veces el cliente necesita saber cuándo ocurre algo en el lado del proveedor: un pago se completa, se entrega un paquete, se firma un documento. El cliente podría sondear (polling), preguntando "¿ya ha ocurrido?" cada pocos segundos, lo que desperdicia solicitudes y aun así se entera tarde. Un webhook invierte el sentido: el cliente registra una URL propia y el proveedor envía un HTTP POST a esa URL cuando se produce el evento. El término lo acuñó Jeff Lindsay en 2007.

Los webhooks traen responsabilidades. El endpoint receptor está en la internet pública, así que debe comprobar que cada llamada procede realmente del proveedor, normalmente verificando una firma criptográfica en una cabecera. Los proveedores reintentan cuando el receptor no responde, así que el mismo evento puede llegar dos veces y el receptor debe reconocer los duplicados (procesar un duplicado no debe hacer que el pedido se envíe dos veces). Y los eventos pueden llegar desordenados.

Esperar una respuesta, o no: síncrono y asíncrono

Todo lo visto hasta ahora ha sido síncrono: quien llama envía una solicitud y espera la respuesta antes de continuar, como en una llamada telefónica. Es fácil de razonar, y es la opción correcta cuando quien llama necesita de verdad la respuesta en ese momento, como "¿se ha aprobado este pago con tarjeta?". Su punto débil es que quien llama solo está tan disponible y es tan rápido como todo aquello de lo que está esperando.

La alternativa es la mensajería asíncrona, más parecida a dejar una carta en un buzón. El emisor pone un mensaje en una cola de mensajes y sigue con lo suyo. El receptor toma los mensajes de la cola cuando está listo. Si el receptor va lento o está caído durante una hora, los mensajes esperan en lugar de fallar. Cuando la tienda confirma un pedido, enviar el correo electrónico de confirmación no tiene por qué bloquear la pantalla del cliente; un mensaje que diga OrderPlaced puede ir a una cola para que el servicio de correo lo gestione un momento después.

La asincronía no es gratis. El emisor no sabe de inmediato si el trabajo ha tenido éxito, el sistema se vuelve más difícil de rastrear y de probar, y los mensajes pueden entregarse más de una vez. Decidir qué interacciones deben ser síncronas y cuáles asíncronas es una de las decisiones centrales de los sistemas distribuidos, tratada a fondo en comunicación y API y en colas y back pressure.

Convivir con las API de otros: SDK, versiones y límites

Muchos proveedores publican un SDK (kit de desarrollo de software): una biblioteca para cada lenguaje popular que envuelve las llamadas HTTP en funciones normales, de modo que un desarrollador escribe client.refunds.create(payment_id) en lugar de construir las solicitudes a mano. Los SDK ahorran tiempo y se ocupan de detalles como los reintentos y las firmas, pero son otra dependencia que hay que mantener al día.

Una vez que una API tiene usuarios, cambiarla se vuelve delicado. Añadir un campo opcional nuevo a una respuesta suele ser seguro. Cambiar el nombre de un campo, eliminarlo, cambiar su tipo o su significado, o hacer obligatoria una entrada opcional es un cambio incompatible (breaking change): todos los clientes que dependían del comportamiento anterior se rompen, a menudo en producción y a menudo para un proveedor que no puede ver ni actualizar esos clientes (piensa en las apps para dispositivos móviles que los usuarios nunca actualizan). Por eso los proveedores asignan una versión a sus API, por ejemplo /v1/ y /v2/ en la URL o una cabecera de versión, mantienen la versión anterior en funcionamiento durante un periodo publicado y anuncian las obsolescencias (avisos de que una función se va a retirar) con mucha antelación. La observación de Hyrum Wright, conocida como ley de Hyrum, añade una advertencia: con suficientes usuarios, alguien dependerá de cada comportamiento observable de una API, incluidos los que la documentación nunca prometió.

Los proveedores también se protegen con un límite de tasa: un tope como 100 solicitudes por minuto y por clave. Las solicitudes que superan el límite se rechazan con el estado 429 Too Many Requests, a menudo con una cabecera Retry-After que indica cuándo volver a intentarlo. Los clientes deben respetarlo, repartir sus solicitudes, guardar en caché las respuestas que no cambian a menudo y retroceder (back off) cuando se les indique.

Usar API de terceros: construir o comprar

Las aplicaciones modernas se ensamblan tanto como se escriben. Una app de reparto de comida podría usar la API de un proveedor de pagos para cobrar con tarjeta, una API de mapas para direcciones y rutas, una API de correo electrónico o SMS para los recibos y un servicio de notificaciones push para avisar de que "tu repartidor está cerca". Cada una ahorra meses de trabajo especializado y aporta una experiencia (seguridad de tarjetas, datos cartográficos globales, entregabilidad del correo electrónico) que pocos equipos podrían igualar.

Cada una aporta también una dependencia que el equipo no controla: las caídas del proveedor se convierten en tus caídas, sus cambios de precio se convierten en tus costos, su tratamiento de los datos pasa a formar parte de tu historia de cumplimiento normativo, y abandonarlo puede obligar a reescribir código. Los profesionales gestionan esto de forma deliberada. Aíslan cada proveedor detrás de una pequeña interfaz propia, de modo que solo una parte del código conozca la API del proveedor; fijan timeouts y deciden qué ocurre cuando el proveedor está caído; vigilan la página de estado y el registro de cambios del proveedor; y anotan lo que costaría cambiar de proveedor.

Por qué esto importa para la arquitectura

La arquitectura trata en gran medida de las partes de un sistema y de los contratos entre ellas, y las API son esos contratos hechos realidad. Una API que es fácil de usar correctamente y difícil de romper permite a los equipos trabajar en paralelo y cambiar libremente su funcionamiento interno; una API con fugas o inestable acopla a todos con todos. La elección entre llamadas síncronas y mensajes asíncronos determina cómo se propagan los fallos. El Capítulo 3 explica los principios de las buenas interfaces (ocultación de información y abstracción), y el Capítulo 6 muestra cómo las decisiones sobre API y mensajería hacen triunfar o fracasar a los sistemas distribuidos.