Qué es una API y cómo funciona: Explicación fácil con ejemplos reales

Cuando abres una app del clima y ves la temperatura actual, esa app no tiene sus propios satélites meteorológicos. Cuando compras algo online y pagas con tarjeta, la tienda no accede directamente a tu banco. Cuando te logueas en una web con tu cuenta de Google, esa web no conoce tu contraseña de Google.

En los tres casos hay algo invisible conectando todo: una API.

Las APIs son la infraestructura oculta del internet moderno. Están en absolutamente todo y, sin embargo, muy poca gente sabe exactamente qué son ni cómo funcionan. Esta guía lo explica de forma clara, con analogías visuales y ejemplos de código real.

¿Qué es una API?

API son las siglas de Application Programming Interface (Interfaz de Programación de Aplicaciones). Es un conjunto de reglas y protocolos que permite que dos aplicaciones se comuniquen entre sí e intercambien datos o funcionalidades.

La definición oficial de Amazon dice que las APIs son "mecanismos que permiten a dos componentes de software comunicarse entre sí mediante un conjunto de definiciones y protocolos". Correcto, pero demasiado abstracto para un principiante. Vamos con la analogía.

La analogía del camarero — la más usada por una razón

Imagina que estás en un restaurante:

• 🧑 Tú eres el cliente (la aplicación que hace la petición)
• 🍳 La cocina es el servidor con todos los datos y la lógica (el backend)
• 🤵 El camarero es la API

Tú no entras a la cocina a buscar tu comida. No necesitas saber cómo funciona la cocina, qué recetas usan ni dónde guardan los ingredientes. Solo le dices al camarero qué quieres, él va a la cocina, recoge lo que pediste y te lo trae.

La API hace exactamente lo mismo: recibe tu petición, la transmite al sistema que tiene los datos, y te devuelve la respuesta. Sin que tú necesites saber nada de cómo funciona el sistema por dentro.

SIN API — acceso directo (imposible y peligroso):
Tu app → accede directamente a la base de datos del banco → obtiene saldo

CON API — acceso controlado:
Tu app → petición a la API del banco: "dame el saldo de la cuenta X"
         → API verifica que tienes permiso
         → API consulta la base de datos internamente
         → API te devuelve: {"saldo": 1250.00, "moneda": "EUR"}
Tu app → muestra el saldo al usuario

Cómo funciona una API — el ciclo petición-respuesta

Toda comunicación con una API sigue siempre el mismo patrón: petición (request) → procesamiento → respuesta (response).

CLIENTE                          SERVIDOR
(tu app, navegador, script)      (la API y sus datos)

1. Petición HTTP
   ─────────────────────────────────────────→
   GET https://api.clima.com/temperatura?ciudad=Madrid
   Headers: Authorization: Bearer tu-api-key

                                2. El servidor procesa:
                                   - Verifica credenciales
                                   - Consulta la base de datos
                                   - Prepara la respuesta

3. Respuesta HTTP
   ←─────────────────────────────────────────
   Status: 200 OK
   Body: {
     "ciudad": "Madrid",
     "temperatura": 23.4,
     "unidad": "Celsius",
     "humedad": 45,
     "actualizado": "2026-04-27T10:30:00Z"
   }

Los ingredientes de una petición API

# Una petición HTTP tiene 4 partes:

# 1. VERBO — qué tipo de operación haces
GET     → leer datos     (obtener información)
POST    → crear datos    (enviar información nueva)
PUT     → actualizar     (reemplazar datos existentes)
PATCH   → actualizar     (modificar solo algunos campos)
DELETE  → eliminar       (borrar datos)

# 2. URL / ENDPOINT — a dónde va la petición
https://api.ejemplo.com/v1/usuarios/123

# 3. HEADERS — información adicional de la petición
Content-Type: application/json    → formato de los datos
Authorization: Bearer mi-api-key  → credenciales de acceso

# 4. BODY — datos que envías (solo en POST, PUT, PATCH)
{
  "nombre": "Ana García",
  "email": "ana@ejemplo.com"
}

Los códigos de estado HTTP — el lenguaje de las respuestas

# Grupos de códigos de estado:

2xx — Éxito ✅
  200 OK           → petición correcta, aquí están los datos
  201 Created      → recurso creado exitosamente
  204 No Content   → operación exitosa, sin datos que devolver

4xx — Error del cliente ❌ (tú hiciste algo mal)
  400 Bad Request  → petición mal formada
  401 Unauthorized → no estás autenticado
  403 Forbidden    → autenticado pero sin permiso
  404 Not Found    → el recurso no existe
  429 Too Many Requests → superaste el límite de peticiones

5xx — Error del servidor 🔥 (el servidor falló)
  500 Internal Server Error → error inesperado en el servidor
  503 Service Unavailable   → servidor caído o en mantenimiento

¿Qué es JSON? — el formato universal de las APIs

Cuando una API te devuelve datos, normalmente los envía en formato JSON (JavaScript Object Notation). Es un formato de texto ligero, legible por humanos y fácilmente procesable por máquinas. Se convirtió en el estándar universal de las APIs modernas.

// Respuesta JSON de una API de usuarios

{
  "id": 1042,
  "nombre": "Ana García",
  "email": "ana@ejemplo.com",
  "activo": true,
  "edad": 28,
  "direccion": {
    "calle": "Av. Principal 123",
    "ciudad": "Madrid",
    "pais": "España"
  },
  "intereses": ["programación", "diseño", "IA"],
  "ultima_conexion": "2026-04-27T09:15:00Z"
}

JSON usa pares clave-valor, puede anidar objetos y listas, y cualquier lenguaje de programación puede leerlo y escribirlo fácilmente.

Tipos de APIs

Por accesibilidad

🌍 API Pública — abierta a todos

Cualquier desarrollador puede usarla, generalmente con registro gratuito para obtener una API key. Son el motor del ecosistema de apps moderno.

Ejemplos de APIs públicas famosas:
  🗺️  Google Maps API      → mapas e integración geográfica
  🌤️  OpenWeatherMap API   → datos meteorológicos
  🐦  Twitter/X API        → tweets y datos de redes sociales
  🚀  NASA APIs            → datos de Mars Rover, imágenes espaciales
  💱  ExchangeRate API     → tipos de cambio de divisas
  🎵  Spotify API          → datos de música y playlists

🔒 API Privada — solo uso interno

Una empresa la crea para uso interno entre sus propios sistemas. El backend le pasa datos al frontend, los microservicios se comunican entre sí. No está disponible para el exterior.

🤝 API de Socio — acceso restringido a socios

Disponible solo para empresas o desarrolladores con acuerdo específico. El banco que da acceso a una pasarela de pago específica, por ejemplo.

Por arquitectura

REST — el estándar dominante

REST (Representational State Transfer) es el estilo arquitectónico más usado en 2026. Usa HTTP, URLs como identificadores de recursos y JSON como formato de datos. Es simple, escalable y legible.

# API REST para gestionar productos:
GET    /api/productos          → obtener todos los productos
GET    /api/productos/42       → obtener el producto con id 42
POST   /api/productos          → crear un nuevo producto
PUT    /api/productos/42       → actualizar el producto 42 completo
PATCH  /api/productos/42       → actualizar solo algunos campos
DELETE /api/productos/42       → eliminar el producto 42

GraphQL — flexible y eficiente

Desarrollado por Meta en 2012. En lugar de múltiples endpoints, tiene uno solo. El cliente especifica exactamente qué datos necesita y recibe solo eso, sin datos extra. Ideal cuando el cliente necesita mucha flexibilidad.

# GraphQL — pides exactamente lo que necesitas
query {
  usuario(id: 42) {
    nombre       # ← solo pides nombre
    email        # ← y email
    # ← NO pides dirección, edad, etc. → no las recibes
  }
}

SOAP — el veterano

Un protocolo más antiguo y rígido que REST. Usa XML en lugar de JSON. Más verboso pero con estándares de seguridad más formales. Aún se usa en sistemas bancarios y corporativos legacy.

WebSocket — comunicación en tiempo real

A diferencia de REST (petición-respuesta), WebSocket mantiene una conexión abierta bidireccional. Ideal para chats, notificaciones en tiempo real, juegos online y feeds financieros.

La API key — tu llave de acceso

La mayoría de APIs públicas requieren una API key (clave de API): una cadena única que te identifica como usuario autorizado. La obtienes al registrarte en el servicio.

# Ejemplo de API key en una petición:

# En la URL (menos seguro):
GET https://api.weather.com/v1/current?ciudad=Madrid&apikey=tu-clave-aqui

# En el header (recomendado):
GET https://api.weather.com/v1/current?ciudad=Madrid
Headers:
  Authorization: Bearer tu-clave-secreta-aqui
  Content-Type: application/json

# ⚠️ NUNCA incluyas tu API key en código que subirás a GitHub
# Guárdala en variables de entorno:
import os
api_key = os.getenv("WEATHER_API_KEY")

Consumir una API con Python — ejemplos reales

Ejemplo 1: API pública de divisas (sin clave)

import requests
import json

# Obtener el tipo de cambio EUR/USD
url = "https://api.exchangerate-api.com/v4/latest/EUR"

respuesta = requests.get(url)

if respuesta.status_code == 200:
    datos = respuesta.json()
    print(f"1 Euro = {datos['rates']['USD']:.4f} USD")
    print(f"1 Euro = {datos['rates']['MXN']:.2f} Pesos mexicanos")
    print(f"1 Euro = {datos['rates']['COP']:.0f} Pesos colombianos")
    print(f"Actualizado: {datos['date']}")
else:
    print(f"Error: {respuesta.status_code}")

Ejemplo 2: API con autenticación (OpenWeatherMap)

import requests
import os

# Tu API key (obtenida gratis en openweathermap.org)
API_KEY = os.getenv("OPENWEATHER_API_KEY")  # guarda en variable de entorno

def obtener_clima(ciudad):
    """Obtiene el clima actual de una ciudad usando la API de OpenWeatherMap."""
    url = "https://api.openweathermap.org/data/2.5/weather"
    parametros = {
        "q":     ciudad,
        "appid": API_KEY,
        "units": "metric",  # Celsius
        "lang":  "es"       # respuesta en español
    }

    try:
        respuesta = requests.get(url, params=parametros)
        respuesta.raise_for_status()  # lanza excepción si hay error HTTP

        datos = respuesta.json()
        return {
            "ciudad":      datos["name"],
            "temperatura": datos["main"]["temp"],
            "sensacion":   datos["main"]["feels_like"],
            "descripcion": datos["weather"][0]["description"],
            "humedad":     datos["main"]["humidity"]
        }
    except requests.exceptions.HTTPError as e:
        print(f"Error HTTP: {e}")
        return None
    except requests.exceptions.ConnectionError:
        print("Error: sin conexión a internet")
        return None

# Usar la función
clima = obtener_clima("Madrid")
if clima:
    print(f"🌍 {clima['ciudad']}")
    print(f"🌡️  Temperatura: {clima['temperatura']}°C")
    print(f"🤔 Sensación térmica: {clima['sensacion']}°C")
    print(f"☁️  {clima['descripcion'].capitalize()}")
    print(f"💧 Humedad: {clima['humedad']}%")

Ejemplo 3: Enviar datos a una API (POST)

import requests

# Crear un nuevo usuario en una API
url = "https://jsonplaceholder.typicode.com/users"  # API de prueba pública

nuevo_usuario = {
    "nombre": "Ana García",
    "email":  "ana@ejemplo.com",
    "ciudad": "Madrid"
}

respuesta = requests.post(
    url,
    json=nuevo_usuario,  # requests convierte automáticamente a JSON
    headers={"Content-Type": "application/json"}
)

if respuesta.status_code == 201:  # 201 = Created
    usuario_creado = respuesta.json()
    print(f"✅ Usuario creado con ID: {usuario_creado['id']}")
else:
    print(f"❌ Error: {respuesta.status_code} - {respuesta.text}")

APIs que usas todos los días sin saberlo

• 🛒 Pagar con tarjeta online — la tienda usa la API de PayPal, Stripe o tu banco para procesar el pago sin acceder nunca a tus datos directamente
• 🗺️ Google Maps en apps de terceros — Uber, Glovo y Airbnb usan la API de Google Maps para mostrar mapas e indicaciones
• 🌤️ App del clima — no tienen sus propios satélites: consumen datos de APIs meteorológicas como OpenWeatherMap o la de la AEMET
• 🔐 "Iniciar sesión con Google" — la API de autenticación de Google verifica tu identidad sin que la web de terceros conozca tu contraseña
• ✈️ Comparadores de vuelos — Skyscanner y Kayak consultan simultáneamente las APIs de decenas de aerolíneas para encontrar los mejores precios
• 🚗 Uber — usa al menos 3 APIs a la vez: Google Maps (navegación), Stripe (pago) y sus propias APIs internas (conductor, viaje)
• 🌐 Compartir en redes sociales — el botón "Compartir en Twitter" de un blog usa la API de Twitter/X

API vs Webhook — la diferencia que confunde

API (petición-respuesta):
  Tu app pregunta: "¿hay nuevos pedidos?"
  La API responde con los datos
  → Tu app tiene que preguntar activamente (polling)

Webhook (evento-notificación):
  Tú dices a Stripe: "cuando proceses un pago, avísame en esta URL"
  Stripe te notifica automáticamente cuando ocurre el evento
  → El servidor te empuja la información cuando pasa algo

Analogía:
  API:     tú llamas al restaurant cada 5 min para saber si tu pedido está listo
  Webhook: el restaurant te llama a ti cuando tu pedido está listo

Tabla resumen: tipos de APIs por arquitectura

Resumen: lo que aprendiste hoy

• ✅ Una API es un conjunto de reglas que permite que dos aplicaciones se comuniquen entre sí
• ✅ La analogía del camarero: tu app (cliente) → API (camarero) → servidor (cocina)
• ✅ El ciclo básico es siempre: petición (request) → procesamiento → respuesta (response)
• ✅ Las peticiones tienen: verbo HTTP, URL/endpoint, headers y body (opcional)
• ✅ JSON es el formato de datos estándar de las APIs modernas
• ✅ Los códigos de estado: 2xx éxito, 4xx error del cliente, 5xx error del servidor
• ✅ Las APIs se clasifican por accesibilidad (pública, privada, socios) y por arquitectura (REST, GraphQL, SOAP, WebSocket)
• ✅ REST es el estándar dominante en 2026: simple, escalable y legible
• ✅ La API key es tu credencial de acceso — nunca la subas a GitHub
• ✅ Con Python y la librería requests puedes consumir cualquier API REST en pocas líneas

🧪 ¿Tienes los fundamentos para construir tus propias APIs?

Consumir APIs es el primer paso. Construir las tuyas propias es el siguiente. Para eso necesitas dominar los fundamentos de JavaScript y las herramientas de backend. Comprueba dónde estás:

👉 Test: Fundamentos de JavaScript 👉 Test: APIs REST Diseño y Consumo 

¿Sabías que usabas APIs a diario antes de leer este artículo? ¿Cuál te parece más útil para tus proyectos: REST o GraphQL? ¿Ya has probado consumir alguna API pública? Cuéntanos en los comentarios 👇 — respondemos todos. 🚀