APIs para diseñadores: qué son y por qué tu app las necesita

¿Qué hace una API, en palabras simples?

Piensa en un enchufe. No necesitas saber cómo se genera la electricidad para usar una lámpara; basta con que el enchufe siga un estándar. Una API funciona parecido: el programa que pide datos no necesita conocer la estructura interna del servicio, solo seguir el formato que el servicio define. Así, un botón de “Buscar” puede hablar con una base de datos que cambió por dentro sin que la interfaz se entere.

MDN define las APIs como construcciones que permiten a los desarrolladores crear funciones complejas con más facilidad, porque abstraen el código complejo y ofrecen una sintaxis más simple en su lugar (MDN, Introduction to client-side web APIs). La misma página distingue dos tipos:

• APIs del navegador: vienen incluidas en el navegador. Un ejemplo es la Web Storage API, que guarda pares nombre/valor en el dispositivo del usuario.
• APIs de terceros: no vienen en el navegador y se consultan por internet. El ejemplo de MDN es la API de Google Maps, que permite mostrar un mapa interactivo en tu sitio.

Un servicio de IA es una API de terceros: tu interfaz le envía un texto y recibe una respuesta.

¿Cómo viaja una petición?

La web usa el protocolo HTTP, que funciona con un modelo cliente-servidor. Según MDN, el navegador es siempre quien inicia la petición; el servidor solo responde (MDN, Overview of HTTP). Cada mensaje tiene partes concretas:

¿Qué significan los códigos de estado?

Los códigos se agrupan por familias, y la familia ya te dice qué tipo de mensaje diseñar. Esta tabla resume los más útiles según el catálogo de MDN (MDN, HTTP response status codes):

Ojo con 401 y 403: aunque el estándar dice “unauthorized”, MDN aclara que el 401 significa “no autenticado” y el 403 que el servidor sabe quién eres pero no te da acceso. Un mensaje dice “inicia sesión”; el otro, “no tienes permiso”.

El 429 merece atención en productos con IA, porque los servicios de modelos suelen limitar cuántas peticiones puedes hacer. MDN llama a ese mecanismo rate limiting y explica que la respuesta puede traer una cabecera Retry-After con el tiempo de espera sugerido (MDN, 429 Too Many Requests). Si existe, tu mensaje puede decir cuánto esperar.

¿Qué pasa cuando una llamada falla o se repite?

Un usuario impaciente pulsa el botón dos veces, o la red se corta justo después de enviar. Ahí aparece una pregunta que el diseño debe resolver: ¿es seguro repetir la petición?

MDN define un método como idempotente cuando el efecto de enviarlo una vez es el mismo que el de enviarlo varias veces. GET, PUT y DELETE lo son; POST no está garantizado: el ejemplo de MDN es que un POST /add_row repetido añade varias filas (MDN, Idempotent).

En el diseño, esto se traduce en tres decisiones:

• Leer es seguro de reintentar. Un botón “Reintentar” en una pantalla de consulta no tiene riesgo.
• Crear o cobrar no lo es. Si una compra falla por un corte de red, el servidor podría haberla procesado igual. Pregunta al equipo técnico cómo se evita el doble cobro antes de poner un botón de reintento.
• Desactiva el botón mientras la petición está en curso. Es la forma más simple de evitar envíos duplicados.

¿Por qué le importa a un diseñador que trabaja con IA?

Porque una interfaz de IA casi nunca tiene el modelo dentro. Envía la pregunta por una API a un servicio externo y muestra la respuesta. Eso tiene consecuencias de diseño:

• La respuesta puede tardar. Cada llamada necesita un estado de carga (estados de carga en IA) y, si el servicio lo permite, se puede mostrar la respuesta mientras llega (streaming de respuestas). Para entender por qué tardan, mira latencia en LLMs.
• Puede fallar o venir incompleta. Cada estado de la conexión necesita su pantalla: cargando, respuesta, error y reintento.
• Cada llamada puede costar dinero. Muchos servicios de IA cobran por uso; ver costo por token. Un botón que dispara llamadas sin límite es también una decisión de costo.
• Las claves no van en el navegador. Las claves que autorizan esas llamadas no deben estar en el código que recibe el usuario. Addy Osmani advierte en Beyond Vibe Coding que el vibe coding deja de ser divertido cuando empiezas a filtrar credenciales de base de datos en el cliente (Osmani, Beyond Vibe Coding). Ver variables de entorno y secretos.

Ejemplo

Ejemplo ilustrativo: un diseñador construye una página donde el usuario escribe una ciudad y ve el clima. La interfaz envía un GET a un servicio con la ciudad en la ruta. Cuando el servicio responde 200, muestra la temperatura. Si responde 404, muestra “No encontramos esa ciudad, revisa la escritura”. Si responde 429, muestra “Hay muchas consultas ahora mismo, espera unos segundos”. Si responde 500, muestra “El servicio de clima no está disponible, intenta de nuevo en unos minutos” con un botón de reintento. Cuatro situaciones, cuatro mensajes, todos salidos del código de estado.

Cómo aplicarlo mañana

1. Haz una lista de las pantallas de tu prototipo que dependen de un servicio externo. Para cada una, escribe qué pide, qué devuelve y qué pasa si falla.
2. Diseña al menos cuatro estados para cada llamada: cargando, éxito, error de la petición (4xx) y error del servidor (5xx). Dibújalos antes de pedir la implementación.
3. Pide a la IA que muestre la respuesta real de la API en la consola, con un ejemplo, antes de conectar la pantalla. Así sabrás qué campos existen de verdad.
4. Prueba la pantalla desconectando la red a propósito. Si el mensaje de error no tiene un siguiente paso, la pantalla no está terminada.
5. Pregunta al equipo técnico qué pasa si el usuario envía la misma petición dos veces.

Errores comunes

• Mostrar el mismo mensaje de error para un 404 que para un 500.
• Decir “no tienes permiso” cuando el problema es que la sesión expiró (401).
• Llamar a un servicio desde el navegador con una clave secreta.
• No diseñar el estado de carga de una respuesta que tarda.
• Poner un botón de reintento en una acción que crea o cobra, sin confirmar que repetirla es seguro.
• Confundir una API con una base de datos: la API es la puerta, no el almacén.

Fuentes

• MDN Web Docs, “Introduction to client-side web APIs”: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction
• MDN Web Docs, “Overview of HTTP”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview
• MDN Web Docs, “HTTP response status codes”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
• MDN Web Docs, “429 Too Many Requests”: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429
• MDN Web Docs, “Idempotent”: https://developer.mozilla.org/en-US/docs/Glossary/Idempotent
• Addy Osmani, “Beyond Vibe Coding”: https://beyond.addy.ie/