Cada vez que consultas el saldo del banco desde el móvil, pagas con tarjeta en una tienda en línea o entras en un servicio con tu cuenta de Google, hay una API trabajando por debajo. Las APIs son el tejido conectivo del software moderno: la manera estándar en que un programa pide algo a otro programa sin necesidad de conocer cómo está hecho por dentro. Esta primera lección define qué es exactamente una API, qué problema resuelve, qué tipos existen y por qué se le llama "contrato". También presenta Tienda Aroma, la tienda de café de especialidad que nos acompañará durante todo el curso, y cierra con un primer ejemplo real de petición y respuesta que iremos desmenuzando en las lecciones siguientes.

1. La idea central: interfaces que ocultan complejidad
2. El problema que resuelve una API
3. La API como contrato entre proveedor y consumidor
4. Ejemplos cotidianos: pasarelas de pago, mapas y login social
5. Tipos de API según su ámbito
6. Qué es una API web y el modelo cliente-servidor
7. Quién consume una API
8. APIs públicas, de socios e internas
9. El escenario del curso: Tienda Aroma
10. Primer ejemplo end-to-end: GET /v1/cafes

API son las siglas de Application Programming Interface, en español "interfaz de programación de aplicaciones". Descompongamos el término:

• Interfaz: un punto de contacto definido entre dos partes. Un enchufe es la interfaz entre un electrodoméstico y la red eléctrica.
• De programación: esa interfaz no la usa una persona con un ratón, la usa otro programa escribiendo código.
• De aplicaciones: las dos partes son piezas de software.

Una API es, por tanto, el conjunto de operaciones que un software ofrece a otro software, descritas de forma que se puedan invocar desde código. Lo esencial es lo que la API no muestra: quien la usa no sabe (ni necesita saber) en qué lenguaje está escrita, qué base de datos hay detrás o cuántos servidores la atienden.

Piensa en la interfaz de un coche: volante, pedales y palanca. Eso es la "API" del coche. Puedes conducir un coche de gasolina y uno eléctrico con la misma interfaz, aunque por dentro sean radicalmente distintos. Si mañana el fabricante cambia el motor, sigues sabiendo conducir. Ese desacoplamiento entre lo que se ofrece y cómo está implementado es el corazón de la idea.

Imagina que Tienda Aroma quiere mostrar su catálogo de cafés en tres sitios: la web de escritorio, una aplicación móvil y una pantalla táctil en su tienda física. Sin API, cada uno de esos tres programas tendría que:

1. Conectarse directamente a la base de datos.
2. Conocer los nombres de las tablas y columnas.
3. Repetir las reglas de negocio (¿un café sin stock se muestra o no?, ¿cómo se calcula el precio con IVA?).

Las consecuencias son predecibles: reglas duplicadas que se desincronizan, credenciales de base de datos repartidas por todas partes y la imposibilidad de cambiar el esquema sin romper tres aplicaciones a la vez.

Con una API, esa lógica vive en un solo sitio y los tres clientes piden lo mismo: "dame los cafés disponibles". Los problemas concretos que resuelve son:

La metáfora más útil para entender una API es la de contrato. Hay dos partes:

• El proveedor (o productor): quien publica y mantiene la API. En nuestro caso, el equipo de backend de Tienda Aroma.
• El consumidor (o cliente): quien la invoca. La app móvil, la web, un socio externo.

El contrato especifica, como mínimo:

• Qué operaciones existen y cómo se invocan (direcciones, verbos, parámetros).
• Qué datos hay que enviar y con qué formato y restricciones.
• Qué se devuelve en caso de éxito: estructura, tipos, unidades.
• Qué ocurre cuando algo falla: cómo se señala un error y qué información se da.
• Qué garantías existen: disponibilidad, límites de uso, política de cambios.

Y como todo contrato, tiene una consecuencia incómoda: una vez publicado, no puedes romperlo unilateralmente. Si Tienda Aroma renombra hoy el campo precioEuros a precio, la app móvil de miles de usuarios dejará de mostrar precios esta misma tarde. Esta idea —que una API es una promesa a largo plazo— explica gran parte de las decisiones de diseño que veremos en el módulo 2, y es la razón de existir del versionado (lección 02-07).

Consejo temprano: diseña pensando que el contrato durará años y que no controlas a quien lo consume. Es un cambio de mentalidad respecto a escribir código interno que puedes refactorizar cuando quieras.

Las APIs son más fáciles de entender con casos que ya has usado como usuario:

• Pasarela de pago: Tienda Aroma no guarda números de tarjeta ni habla con los bancos. Envía a la API de la pasarela el importe y una referencia del pedido, y recibe una confirmación. La complejidad brutal del sistema de pagos queda detrás de una operación de un par de campos. Además evita responsabilidades regulatorias enormes.
• Mapas: para mostrar dónde está la cafetería física, la web pide a una API de mapas un mapa centrado en unas coordenadas. Nadie en Tienda Aroma dibuja calles.
• Login social ("Entrar con Google"): la tienda no gestiona contraseñas; delega la autenticación en un proveedor de identidad y recibe la confirmación de quién es el usuario. Veremos el mecanismo real (OAuth 2.0 y OpenID Connect) en la lección 04-03.
• Envíos: cuando un pedido se marca como pagado, Tienda Aroma llama a la API de su empresa de mensajería, RápidoEnvíos, para generar la etiqueta y obtener un número de seguimiento.

El patrón se repite: no construyas lo que puedes consumir; no expongas por dentro lo que puedes ofrecer por fuera.

No todas las APIs viajan por la red. Conviene distinguir tres ámbitos, porque el término se usa para los tres:

Un ejemplo de API de biblioteca que ya conoces:

Las tres comparten filosofía, pero las APIs web tienen una diferencia crucial: la llamada cruza la red. Eso introduce latencia, fallos de conexión, seguridad, control de acceso y versiones que conviven. Este curso trata exclusivamente de APIs web y, dentro de ellas, del estilo REST.

Una API web es una API a la que se accede mediante el protocolo HTTP a través de una dirección de red. Funciona bajo el modelo cliente-servidor:

• El cliente toma la iniciativa: envía una petición.
• El servidor escucha, procesa y devuelve una respuesta.
• La conversación siempre la empieza el cliente (los webhooks, en 01-07, invierten esa dirección).

Observa dos detalles importantes del diagrama:

1. El cliente nunca habla con la base de datos. Solo conoce la dirección de la API.
2. Lo que devuelve la API no son "filas de una tabla", sino una representación en JSON pensada para ser consumida. Esta distinción entre el dato interno y su representación es central en REST y la desarrollaremos en la lección 01-04.

Saber quién está al otro lado cambia el diseño. Los consumidores típicos de la API de Tienda Aroma:

• Aplicación web de página única (SPA): la tienda en línea. Se ejecuta en el navegador y pide datos por JavaScript. Es sensible al número de peticiones y a las políticas de seguridad del navegador (CORS, lección 04-05).
• Aplicación móvil nativa: Aroma Móvil, para iOS y Android. Peculiaridad crítica: el usuario decide cuándo actualiza, así que versiones antiguas seguirán llamando a tu API durante meses.
• Otro servicio del backend: el servicio de facturación pregunta a la API por los pedidos del mes. Es tráfico interno, con requisitos de rendimiento distintos.
• Integraciones de terceros: RápidoEnvíos consulta los pedidos pendientes de recogida; una herramienta de contabilidad exporta las ventas.
• Herramientas y scripts: curl, Postman (lección 05-01), scripts de mantenimiento del propio equipo.

Según a quién se abra la puerta, se distinguen tres categorías. Es una decisión de negocio con enormes implicaciones técnicas:

Un error frecuente es tratar la API interna como si no necesitara disciplina. Cuando la empresa crece, la API interna acaba teniendo diez consumidores que no controlas en el día a día, y la falta de contrato se paga cara.

A partir de aquí, todo lo que aprendamos se aplicará sobre un caso único, para que los conceptos no queden en abstracto.

Tienda Aroma es una tienda en línea de café de especialidad. Vende cafés de origen, tuestes propios y suscripciones mensuales. Su realidad técnica es:

• Una tienda web hecha como SPA.
• Una app móvil, Aroma Móvil, con la que los clientes repiten pedidos.
• Un panel interno de administración que usa el equipo de almacén y atención al cliente.
• Una integración con RápidoEnvíos, la empresa de mensajería que reparte los pedidos.

Sus recursos (las "cosas" que maneja el negocio) son cinco, y serán los mismos durante todo el curso:

La API vive en https://api.tiendaaroma.example/v1 y en realidad son dos APIs con el mismo dominio de negocio: una pública (catálogo y reseñas, para que blogs y comparadores puedan mostrar sus cafés) y una interna (pedidos, stock, clientes) usada por el panel de administración y por RápidoEnvíos como socio.

A partir del módulo 3 la implementaremos con Node.js 20 y Express, escribiendo los identificadores en español (obtenerCafes, crearPedido, precioEuros) para que el código sea fácil de leer.

Veamos la API más simple posible en acción: pedir el catálogo. Usaremos curl, una herramienta de línea de comandos que envía peticiones HTTP y muestra la respuesta. Está disponible en Linux, macOS y Windows 10 o superior.

Esa línea contiene tres cosas: el programa (curl), y una dirección que a su vez indica dónde está la API (api.tiendaaroma.example), que hablamos por canal cifrado (https) y qué pedimos (/v1/cafes, la lista de cafés de la versión 1 de la API). Al no indicar nada más, curl usa el método GET, que significa "dame esto sin modificar nada".

La respuesta que devuelve el servidor:

Analicemos la respuesta pieza a pieza, sin entrar todavía en el detalle del protocolo:

• Está en JSON (JavaScript Object Notation), el formato de intercambio dominante hoy. Los {} delimitan objetos con pares clave: valor, y los [] delimitan listas.
• La clave datos contiene la lista de cafés. Envolver la lista dentro de un objeto (en lugar de devolver el array directamente) deja sitio para añadir metadatos como total sin romper el contrato.
• Cada café tiene un id estable (caf_001). Ese identificador es lo que permite pedir después un café concreto: GET /v1/cafes/caf_001.
• precioEuros deja explícita la unidad en el nombre del campo. Un campo llamado solo precio obliga a leer la documentación para saber si son euros o céntimos: una fuente clásica de errores.
• tueste usa un valor de un conjunto cerrado y conocido (claro, medio, oscuro).

Si en lugar de la lista queremos un café concreto, cambiamos la dirección:

Fíjate en un detalle nada casual: la dirección del recurso individual es la de la colección más su identificador. Esa regularidad, que ahora parece anecdótica, es una de las señas de identidad de REST y la formalizaremos en la lección 01-04.

Todo lo que ocurre por debajo (cabeceras, códigos de estado, métodos) lo veremos en la lección 01-03, dedicada a HTTP. De momento quédate con la imagen completa: un cliente pide algo a una dirección y un servidor responde con una representación en JSON.

• Confundir la API con la base de datos. La API no es una ventana a las tablas: es una interfaz de negocio. Exponer el esquema interno tal cual te ata para siempre a ese esquema.
• Confundir la API con la aplicación web. La web es un consumidor. Si diseñas la API pensando solo en la pantalla que estás construyendo hoy, la app móvil que llegue mañana no encajará.
• Creer que "API" siempre significa "API web". En una oferta de trabajo o en una conversación, conviene precisar de qué ámbito se habla (biblioteca, sistema operativo o red).
• Olvidar que el contrato es una promesa. Antes de publicar un nombre de campo, piensa si querrás mantenerlo dentro de dos años.
• No nombrar las unidades. precioEuros, pesoGramos o duracionSegundos ahorran incidencias reales en producción.
• Consejo: cuando empieces a diseñar, escribe primero un ejemplo de petición y de respuesta JSON, como el de esta lección, antes de escribir una sola línea de servidor. Es la esencia del enfoque API-first que veremos en 01-02 y 05-02.

Tienda Aroma quiere que un blog de cafés externo muestre en su web los tres cafés más vendidos. Enumera al menos cinco elementos que debería especificar el contrato de esa API para que el blog pueda integrarse sin preguntar nada por correo electrónico.

Para cada situación, indica quién es el consumidor y si la API implicada debería ser pública, de socios o interna, justificándolo brevemente:

1. El panel de administración marca un pedido como enviado.
2. Un comparador de precios muestra el catálogo de Tienda Aroma.
3. RápidoEnvíos consulta cada 10 minutos los pedidos pendientes de recoger.
4. Aroma Móvil muestra el historial de pedidos del usuario que ha iniciado sesión.

Diseña el JSON que devolvería GET /v1/cafes/caf_002/resenas (las reseñas de un café). Debe incluir al menos dos reseñas, con identificador, autor, puntuación de 1 a 5, comentario y fecha. Aplica lo aprendido sobre nombres de campo, unidades y envoltorio de la lista.

Solución 1

Un contrato mínimo utilizable debería especificar:

1. La dirección exacta de la operación, por ejemplo GET https://api.tiendaaroma.example/v1/cafes?ordenar=masVendidos&limite=3.
2. Cómo se autentica el blog: si necesita clave de API y cómo se envía.
3. La estructura de la respuesta: qué campos vienen, de qué tipo y cuáles pueden faltar (nombre texto, precioEuros número decimal, stock entero).
4. El comportamiento ante errores: qué se devuelve si la clave es inválida o el servicio no está disponible, y cómo distinguirlo de una respuesta correcta vacía.
5. Los límites de uso: cuántas peticiones por minuto se admiten y qué ocurre al superarlos.

Elementos adicionales igualmente válidos: política de versionado y aviso de cambios, condiciones de uso de los datos y de las imágenes, y contacto de soporte.

Solución 2

1. Panel de administración → API interna. Modifica el estado del negocio y solo la usa personal de la empresa.
2. Comparador de precios → API pública. Solo lee catálogo, información no sensible; interesa comercialmente que se difunda.
3. RápidoEnvíos → API de socios. Es una empresa externa concreta con acuerdo previo, con credenciales propias y acceso limitado a los pedidos que le corresponden.
4. Aroma Móvil → API interna (aunque accesible desde internet). Es un cliente propio que accede a datos personales; requiere autenticación del usuario y devolver únicamente sus pedidos.

Observa el matiz del caso 4: "interna" se refiere a quién la controla y para quién se diseña, no a si es alcanzable desde la red.

Solución 3

Decisiones a destacar: la lista va envuelta en datos para poder añadir metadatos; cada reseña lleva cafeId para que sea autoexplicativa aunque se copie fuera de contexto; puntuacion es un número entero y no un texto; y la fecha usa el formato ISO AAAA-MM-DD, que es inequívoco internacionalmente (frente a 14/07/2026, que un consumidor estadounidense podría leer mal).

Una API es una interfaz que permite a un programa usar los servicios de otro sin conocer su interior, y su valor está tanto en lo que expone como en lo que oculta. Hemos visto que funciona como un contrato entre proveedor y consumidor, que existen APIs de biblioteca, de sistema operativo y web, y que estas últimas siguen el modelo cliente-servidor sobre HTTP. También hemos clasificado las APIs en públicas, de socios e internas, y hemos conocido a Tienda Aroma, cuyos cinco recursos —cafés, clientes, pedidos, reseñas y carritos— nos servirán de laboratorio hasta el final del curso. El primer GET /v1/cafes ya nos ha mostrado el patrón fundamental: petición a una dirección, respuesta en JSON.

Antes de entrar en cómo se diseñan estas interfaces, conviene entender de dónde vienen. En la siguiente lección, Historia y evolución de las APIs, recorreremos el camino que va de las llamadas a procedimiento remoto a la economía de las APIs actual, para comprender por qué REST se impuso y qué lecciones prácticas deja esa historia a quien diseña una API hoy.