Hace unos días me encontré con unas notas viejas de cuando daba clases en la universidad. Eran apuntes sobre APIs: algunas diapositivas, notas sueltas de estudio y explicaciones que tenía preparadas para clase. Nada demasiado formal, pero sí material que usaba para explicar el tema sin aventarlo de golpe como si todos ya vinieran con contexto.
Me dio gusto volver a verlas porque, en su momento, esas notas funcionaron.
Recuerdo que varios alumnos lograban entender el concepto, bajarlo a tierra y explicarlo con sus propias palabras. Incluso llegábamos a ese punto que para mí era la mejor señal: que pudieran explicárselo a un niño de 12 años y que este niño, al menos, se llevara una idea clara de lo que estaba pasando.
Ahí es cuando sabes que algo se entendió de verdad.
Por eso no quería dejar esas notas perdidas entre diapositivas, Notion o apuntes de texto que probablemente no iba a volver a abrir. Preferí convertirlas en un post. No como una clase pesada, ni como una explicación para gente senior, sino como una guía tranquila para alguien que está empezando o para alguien que ya ha usado APIs de forma empírica, pero nunca se ha detenido a ordenar bien la idea.
Porque la palabra API aparece por todos lados: en tutoriales, cursos, documentación, proyectos reales, integraciones con pagos, mapas, bancos, WhatsApp, inteligencia artificial o sistemas internos. Y muchas veces se menciona como si todos ya supieran exactamente qué significa.
Pero no siempre es así.
Primero lo básico: ¿qué significa API?
API significa Application Programming Interface. En español normalmente se traduce como Interfaz de Programación de Aplicaciones.
Suena más complicado de lo que realmente es.
Y creo que ahí empieza parte del problema. A veces nos topamos con una definición formal, llena de palabras correctas, pero no necesariamente clara para alguien que apenas está entrando al tema. Entonces vamos a bajarlo un poco.
En pocas palabras, una API es una forma ordenada para que una aplicación le pida algo a otra aplicación y reciba una respuesta.
Eso es todo para empezar.
Una aplicación necesita algo. Otra aplicación puede dárselo. La API define cómo se lo tiene que pedir.
Una API sirve para que dos sistemas se entiendan
Imagina que tienes una aplicación que necesita mostrar información, guardar datos, consultar usuarios, mandar mensajes, procesar pagos o pedirle algo a otro sistema. Esa aplicación no debería meterse directamente a la base de datos del otro sistema. Tampoco tendría sentido que cada integración funcionara con reglas inventadas sobre la marcha.
Ahí aparece la API.
La API funciona como una forma controlada de comunicación. Le dice al sistema externo algo como:
Si quieres pedirme algo, hazlo por aquí.
Con este formato.
Con estas reglas.
Y yo te responderé de esta manera.Eso es importante porque una API no solo conecta sistemas. También pone orden.
Sin una API, cada sistema tendría que encontrar su propia manera de hablar con los demás. Sería frágil, confuso y difícil de mantener. Con una API, en cambio, existe un camino definido para pedir información o ejecutar una acción.
La analogía del mostrador
Una forma sencilla de verlo es pensar en un mostrador.
Llegas a un lugar donde necesitas pedir algo. No entras a las oficinas internas, no revisas todos los archivos, no te metes a las computadoras y no vas directo al almacén. Llegas al mostrador y haces una petición.
Por ejemplo:
Necesito consultar este dato.La persona del mostrador revisa tu solicitud, valida si puede atenderla, busca la información y te responde. Tal vez te diga que sí encontró lo que pediste. Tal vez te diga que no existe. O quizá te diga que no tienes permiso para consultar esa información.
Con una API pasa algo parecido.
Tú no ves todo lo que ocurre por dentro. No sabes cómo está construida la base de datos, no conoces toda la lógica interna y no necesitas saber qué servidores están trabajando detrás. Solo haces una petición siguiendo ciertas reglas y recibes una respuesta.
En cristiano: no entras hasta la cocina. Pides por la ventanilla correcta.
Un ejemplo con JSONPlaceholder
Para no quedarnos solo con teoría, vamos a usar un escenario real de práctica: JSONPlaceholder.
JSONPlaceholder es una API falsa, pero muy útil para aprender. Tiene datos de ejemplo como publicaciones, comentarios, usuarios y tareas. No estás tocando información real de una empresa, no puedes romper nada importante y puedes practicar con calma.
Por ejemplo, existe este endpoint:
https://jsonplaceholder.typicode.com/postsSi lo abres en el navegador, te devuelve una lista de publicaciones falsas.
La idea, simplificada, sería esta:
Mi aplicación pide: dame las publicaciones.
La API responde: aquí tienes las publicaciones.Eso ya es una API trabajando.
Claro, detrás hay más detalles técnicos. Hay métodos HTTP, respuestas en JSON, códigos de estado, headers, body y muchas otras cosas que iremos viendo después. Pero para esta primera parte lo importante es entender la idea base: una aplicación está pidiendo información a otro sistema a través de una forma definida.
Y ese otro sistema responde.
Entonces, ¿una API es una URL?
Aquí aparece una confusión muy común.
Alguien podría decir: “entonces una API es una URL”.
Y la respuesta corta sería: más o menos, pero no exactamente.
Muchas APIs se consumen usando URLs, sí. Por ejemplo:
https://jsonplaceholder.typicode.com/postsEsa dirección se puede abrir en el navegador y devuelve información. Entonces es normal que alguien piense que la API es el link.
Pero no.
La URL es solo una parte.
Una API completa incluye más cosas: qué direcciones existen, qué puedes pedir en cada una, qué método debes usar, qué datos puedes enviar, qué formato tendrá la respuesta, qué errores pueden aparecer y qué reglas debes respetar.
Decir que una API es solo una URL se queda corto. Es como decir que una casa es solamente la puerta. La puerta importa, claro, pero la casa no es solo la puerta.
La palabra correcta: endpoint
A esas URLs específicas dentro de una API normalmente se les llama endpoints. También puedes escucharlas como rutas o recursos, dependiendo del contexto.
Por ejemplo, en JSONPlaceholder existen endpoints como estos:
https://jsonplaceholder.typicode.com/posts
https://jsonplaceholder.typicode.com/comments
https://jsonplaceholder.typicode.com/usersTodo eso pertenece a la misma API, pero cada dirección apunta a un recurso distinto. Uno sirve para publicaciones, otro para comentarios y otro para usuarios.
Entonces podemos decirlo así:
La API es el conjunto completo.
El endpoint es una dirección específica dentro de esa API.En conversaciones informales muchas personas dicen “pégale a esta API” cuando en realidad se refieren a “consume este endpoint”. Y normalmente se entiende. Pero en ambientes más técnicos conviene conocer la diferencia.
No por quedar elegante.
Sino porque ayuda a pensar mejor.
Sobre todo cuando trabajas en equipos donde se diseñan integraciones, se documentan servicios o se discuten decisiones de arquitectura. Ahí sí importa distinguir entre la API completa y cada endpoint específico.
Una API también es un contrato
Otra forma útil de entender una API es verla como un contrato entre sistemas.
No contrato en el sentido legal, sino en el sentido técnico: un acuerdo. La API define qué se puede pedir, cómo se debe pedir y qué tipo de respuesta se puede esperar.
Por ejemplo, JSONPlaceholder nos deja intuir algo como esto:
Si consultas /posts, te devuelvo publicaciones.
Si consultas /users, te devuelvo usuarios.
Si consultas /comments, te devuelvo comentarios.Eso permite que otros sistemas puedan integrarse sin conocer todo lo que pasa por dentro. También permite que el sistema que ofrece la API mantenga control, porque no expone todo, solo expone caminos específicos para hacer cosas específicas.
Y eso es muy importante en sistemas reales.
Una API bien pensada no abre la puerta a todo. Abre las puertas necesarias, con reglas claras.
¿Por qué esto importa?
Porque casi todo lo que usamos hoy se comunica con algo más.
Una app del clima necesita datos del clima. Una tienda en línea necesita procesar pagos. Un sistema administrativo necesita consultar clientes, facturas o productos. Una aplicación móvil necesita iniciar sesión, traer información y guardar cambios. Una herramienta de inteligencia artificial necesita recibir una instrucción y devolver una respuesta.
Detrás de muchas de esas acciones hay APIs.
El usuario final solo ve un botón, una pantalla o un mensaje de carga. Pero detrás puede haber varias peticiones entre sistemas. Un sistema pregunta algo. Otro sistema responde. A veces responde bien. A veces dice que no encontró nada. A veces dice que no tienes permiso. A veces falla.
Pero ya hay una conversación ocurriendo.
Y cuando entiendes eso, empiezas a ver las aplicaciones de otra manera. Ya no ves solamente pantallas. Empiezas a ver sistemas hablando entre sí.
No hace falta aprender todo de golpe
Aquí conviene ir con calma.
Cuando uno empieza a estudiar APIs, rápido aparecen muchas palabras: GET, POST, headers, body, JSON, token, REST, status code, endpoint, request, response.
Y sí, todo eso importa.
Pero no todo tiene que entrar en la primera explicación.
Primero hay que entender la idea base: una API es una forma ordenada para que un sistema le pida algo a otro sistema.
Después ya podemos hablar de cómo se hace esa petición, qué método se usa, qué datos se mandan, cómo responde la API y qué pasa cuando algo falla.
Conclusión
Una API no tiene que ser un concepto intimidante. Muchas veces el problema no es que sea imposible de entender, sino que se explica empezando demasiado arriba.
Por eso quise recuperar estas notas y convertirlas en una serie. Porque si alguien está empezando, o si ya ha usado APIs copiando ejemplos sin entender del todo qué está pasando, vale la pena volver a la base.
Una API permite que dos sistemas se comuniquen de forma ordenada. La API es el conjunto de reglas. Los endpoints son las direcciones específicas donde haces peticiones. Y servicios como JSONPlaceholder nos permiten practicar sin romper nada real.
Hasta aquí no necesitamos meternos todavía con métodos HTTP, headers, body o tokens.
Eso viene después.
Primero había que entender la puerta.
En el siguiente post vamos a tocarla.