¿Qué es una API? Guía básica para dueños de pequeños negocios

Hola, soy yeonghyeon, lidero el desarrollo en 3Min API.

En la entrega anterior, la publicación sobre bases de datos, cerramos la historia del dueño de la tienda de vinos dejando adrede una cosa para más tarde. Dije que, una vez abierta la tienda online, los pedidos del POS de la tienda, del sitio web y de los restaurantes asociados se acumulan automáticamente en la misma base de datos — pero la herramienta que se esconde detrás de esa palabra "automáticamente" es el tema de hoy. Es la API.

Esta publicación tiene un único objetivo. Antes de estudiar la tecnología compleja detrás de la palabra "API", primero queremos construir el sentido de "organizar el flujo de su negocio como mensajes acordados, no solo en su cabeza". Una vez que tenga ese sentido, lo demás vendrá de forma natural cuando lo necesite. No hace falta ningún conocimiento previo.

¿Qué es una API?

Empecemos con la definición del diccionario. Wikipedia describe una API (Application Programming Interface) como "un conjunto de reglas que permite que las aplicaciones intercambien funciones y datos entre sí".

En una frase:

API = una ventanilla construida para que los sistemas intercambien datos entre sí siguiendo reglas acordadas.

Hay varios estilos de API, pero el más utilizado hoy en la web con diferencia es la REST (o RESTful) API. La historia de hoy usa REST como línea base. No entraremos en los detalles técnicos de REST. Desde el punto de vista del negocio, basta con una intuición: "cuando envía un mensaje con una forma determinada a una dirección determinada, recibe una respuesta con una forma determinada".

Un detalle que conviene marcar aquí. Una API siempre devuelve una respuesta a cada petición. Esa respuesta queda zanjada primero por un único número que distingue éxito de fallo, y a continuación llega el detalle. Si el pedido se guardó correctamente, o por qué fue rechazado — todo vive dentro de esa respuesta. La forma concreta la volveremos a ver más adelante junto con la historia de la tienda de vino.

¿Por qué hace falta una "ventanilla"?

Piense en un banco por un momento. En la cámara acorazada del banco está el dinero de todos los clientes, pero ningún cliente entra directamente en la cámara. En su lugar, un empleado de ventanilla recibe las peticiones en un formato fijo (comprobantes de depósito o retiro), verifica la identidad y luego las procesa. Incluso el empleado de ventanilla no entra y sale libremente de la cámara. Las reglas y los permisos están definidos.

Con una base de datos pasa lo mismo. Técnicamente es posible conectarse directamente a una DB por internet y leer y escribir datos, pero en el momento en que esa puerta queda abierta para cualquiera, el negocio se derrumba. Alguien puede llevarse la lista completa de clientes, alguien puede cambiar el precio de un producto a cero, alguien puede borrar por entero la tabla de inventario.

Por eso se coloca una API como ventanilla delante de la base de datos. Toda petición externa debe pasar por ella. La ventanilla hace tres cosas: validar (¿tiene el formato correcto?), autenticar y autorizar (¿quién es y qué puede hacer?), y ejecutar solo acciones dentro del rango permitido (un cliente puede consultar únicamente sus propios pedidos y nunca editar el precio). Quien toca el mundo exterior es la API, no la DB.

La API del dueño de la tienda de vinos

Continuemos desde la última escena de la publicación anterior. El dueño de la tienda de vinos abrió su tienda online, y ahora el POS de la tienda, el sitio web y los restaurantes asociados miran la misma base de datos al mismo tiempo. Esa imagen se sostiene por una sola razón: cada uno accede a la DB únicamente a través de una API.

Si traducimos a lenguaje natural lo que envía cada uno de los tres, queda así:

• POS de la tienda → "Por favor, guarda un pedido." (escritura)
• Tienda online → "Dame la lista de vinos que Alex compró el mes pasado." (lectura)
• Restaurante asociado → "Por favor, reduce en 10 botellas el stock de Château Margaux 2020." (actualización)

Cada petición llega a una dirección acordada (URL), dentro de un mensaje con una forma acordada. Ese mensaje suele ser un único bloque empaquetado en un formato llamado JSON. Si la palabra JSON le suena rara, puede echar un vistazo a la publicación anterior de Chae-won, sus datos merecen un plan. Por hoy, imagínelo como "un sobre que transporta un bloque de datos con un formato acordado".

Una vez que las direcciones y la forma de los mensajes están alineadas, los pedidos siguen entrando automáticamente mientras el dueño de la tienda duerme, y la DB los va acumulando con la misma forma. Ningún empleado tiene que retecleaer nada; ningún encargado de la tienda online tiene que fusionar hojas de cálculo. La automatización fue posible porque se fijaron las reglas.

Entonces, ¿qué pasa después de que la ventanilla recibe la petición? Siempre vuelve una respuesta. Esa respuesta queda decidida primero por un solo número, no por una frase humana. Este número se llama código de estado HTTP y, aunque hay decenas de ellos, a un propietario de negocio le basta con reconocer tres familias.

• Serie 200 — Éxito: la petición se procesó correctamente. El pedido quedó guardado, o los datos consultados llegan también en la respuesta. (ej. 200 OK, 201 Created)
• Serie 400 — Petición incorrecta: el problema está en el mensaje que se envió. Falta un campo obligatorio, falta la autorización, o la dirección no existe. (ej. 400 Bad Request, 401 Unauthorized, 404 Not Found)
• Serie 500 — Problema del lado del servidor: algo se rompió dentro de la propia ventanilla. Aun con una petición correcta puede fallar, así que los sistemas se diseñan para reintentar tras una pequeña pausa. (ej. 500 Internal Server Error)

Detrás del número suele llegar un bloque de JSON. En caso de éxito, lleva el ID del pedido guardado; en caso de fallo, describe qué estaba mal y por qué. Si envía a la API de la tienda de vino "un pedido al que le falta el campo quantity", la ventanilla responde con un 400 y un mensaje del tipo "el campo quantity es obligatorio". Gracias a este acuerdo, sistemas con sistemas — y personas con sistemas — pueden distinguir el éxito del fallo en el mismo lenguaje.

Las APIs están, de hecho, en todas partes

Aunque dejemos la historia de la tienda de vinos, casi todas las apps que usó hoy estaban llamando a la API de alguien por debajo. El feed de Instagram se arma leyendo la DB del servidor a través de una API; un conductor de Tesla que consulta el estado del coche en la app móvil, una app del clima que avisa de lluvia, una app de delivery que muestra el menú de un restaurante — todo es lo mismo. Hasta el botón de pedido de una nevera, el asistente de voz de un coche o los altavoces inteligentes recientes funcionan sobre APIs.

La API de la que hemos hablado hasta ahora era el estilo "cuando yo lo necesito, me acerco a la ventanilla de la otra parte y envío una petición". Al revés, también existe la forma en la que el otro sistema viene primero a mi ventanilla y me dice "acaba de pasar esto". El caso más claro es la pasarela de pago enviando una notificación a mi servidor en el instante en que un pago se completa. A esa forma se le da otro nombre: webhook.

En realidad, API y webhook son técnicamente lo mismo. La dirección de la petición, la forma del mensaje, el método de autenticación, los códigos de respuesta — no hay una sola diferencia. Son la misma herramienta intercambiando un bloque de JSON sobre la misma ventanilla HTTP, y el código que los llama es casi indistinguible. ¿Y por qué usar entonces dos nombres distintos? Las primeras APIs web se diseñaron sobre todo para el caso "cuando yo necesito algo, lo pido y me lo traigo". Con el tiempo, la dirección contraria — "cuando ocurre un evento, la otra parte me lo empuja primero" — se volvió cada vez más frecuente, y alrededor de 2007 se acuñó el nombre webhook específicamente para esa dirección inversa. La tecnología no se dividió en dos; simplemente se añadió un segundo nombre de rol a la misma herramienta.

Así que basta con recordarlo así: si llamo yo primero, es una API; si llama primero la otra parte, es un webhook.

Entonces, ¿cómo se construye una API?

Al llegar aquí es natural pensar: "Vale, solo tengo que hacer una API para mi negocio también". Pero para que una API realmente "corra 24/7 de forma segura", hacen falta más piezas de las que uno esperaría. Las enumero con honestidad:

• Una dirección fija: debe poder invocarse desde internet, así que hay que comprar un dominio, configurar DNS y colocar un certificado HTTPS.
• Un servidor en vivo 24/7: si uno cae, se detienen las ventas. Hacen falta varios servidores, detección de fallos y recuperación automática.
• Código: código propio que reciba peticiones, las valide, distinga errores, devuelva respuestas con una forma determinada y deje registros.
• Autenticación y permisos: hay que distinguir quién puede llamar a qué API. Emitir claves de API, caducarlas y desactivar las robadas es una operación continua.
• Integración con base de datos: la DB se instala y opera aparte. Copias de seguridad, seguridad y rendimiento corren en paralelo a la API.
• Escalado y monitoreo: cuando sube el tráfico en temporada, debe escalar hacia arriba automáticamente; el resto del tiempo debe reducirse para ahorrar costos. También hace falta un panel que vigile en tiempo real la tasa de errores, el tiempo de respuesta y el costo.

No hay que construir todas estas piezas a solas. Plataformas en la nube como AWS, Google Cloud, Cloudflare, Firebase y Supabase ofrecen cada una de esas piezas. Pero elegir, conectar y operar las piezas es en sí mismo un terreno especializado. Si un dueño de negocio lo construye desde cero, suele ocupar de varias semanas a varios meses de trabajo de un desarrollador backend.

Resumen hasta aquí

Lo atamos con pocas líneas:

• Una API es la ventanilla que le permite acceder a la base de datos de forma segura.
• La ventanilla solo acepta peticiones en direcciones acordadas con mensajes de forma acordada.
• Gracias a ese acuerdo, muchos sistemas pueden avanzar mirando los mismos datos al mismo tiempo.
• Mientras usted duerme, las APIs están siendo llamadas y quien lo necesita llama a otra API. El cuerpo real de la automatización se apoya sobre esos acuerdos.

Lo que puede probar hoy mismo

En la entrega anterior, la publicación sobre bases de datos, dibujamos la estructura de datos de un negocio en tres hojas de Excel. Hoy imaginemos la "ventanilla" por la que circulan esos datos. Solo necesita su cabeza y una IA — no hace falta código, ni servidor, ni pagar nada.

Acción 1. Dibujar un endpoint para su negocio

Elija una de las hojas "personas / cosas / transacciones" de la publicación anterior y defina "el evento que trae una nueva fila a esta hoja". Ejemplo: "cuando entra un pedido nuevo en la tienda online". Escriba solo tres líneas en un papel:

1. Nombre del evento: p. ej., pedido creado
2. Quién lo envía: p. ej., tienda online, POS de la tienda, formulario de contacto
3. Qué datos lleva: p. ej., número de cliente, número de producto, cantidad, importe

Estas tres líneas son el diseño de un endpoint. El primer boceto que un desarrollador dibuja cuando va a construir una API vive exactamente en este nivel de detalle.

Acción 2. Pedir a una IA el plan completo

Junto con sus notas de la Acción 1, pegue el siguiente prompt en ChatGPT, Claude o Gemini (cualquiera de ellos):

Usando la siguiente documentación de servicio, guíeme paso a paso, en términos
que un no desarrollador pueda entender, sobre cómo podría implementar realmente
el endpoint que acabo de esbozar.

https://3minapi.com/llms-full.txt

Lo más probable es que la respuesta apunte a "crear un endpoint y enviar cada pedido como un único bloque JSON". No se asuste si los términos le resultan extraños — solo recuerde que se trata de abrir esa única "ventanilla" que aprendimos hoy.

Acción 3. Pruebe su primera API en tres minutos

Comprar un dominio, levantar un servidor e instalar usted mismo una DB es demasiado para esta etapa. Siga la guía de inicio rápido de abajo y podrá recorrer todo el flujo — crear una base de datos → crear un endpoint de API → llamarlo → confirmar que el registro llegó a la DB — en menos de tres minutos.

Aquí puede surgir una pregunta: "He creado una API, pero ¿cuándo creé la base de datos?". Como mencioné antes, normalmente se instala y opera la DB por separado, pero en 3Min API, cuando define los campos de un endpoint, el espacio de almacenamiento correspondiente se crea automáticamente por detrás al mismo tiempo. Desde el punto de vista del dueño, basta con diseñar la ventanilla (API) — la caja fuerte (DB) se prepara junto a ella. Por eso "3 minutos" forma parte del nombre.

👉 Cómo crear un endpoint sin un desarrollador — guía de inicio rápido

Próxima entrega

En la entrega anterior miramos el recipiente que contiene los datos y hoy miramos la ventanilla que une ese recipiente con el mundo exterior. Si llegó hasta aquí, queda una pregunta: "¿Qué forma tienen exactamente los mensajes que circulan entre los recipientes?"

En la próxima entrega cubriremos la forma de esos mensajes: JSON. Siga adelante para ver exactamente en qué sobre viaja un pedido de la tienda de vinos al pasar del POS al servidor, y del servidor a la tienda online.

---

← Anterior: ¿Qué es una base de datos? Guía básica para usuarios de Excel
→ Siguiente: ¿Qué es JSON? Guía básica para dueños de pequeños negocios