¿Qué es una API? Guía con Ejemplos Reales

Las APIs (Application Programming Interfaces) son la columna vertebral del software moderno. Permiten que aplicaciones, servicios y dispositivos se comuniquen entre sí, compartiendo datos o funcionalidades sin exponer su estructura interna. Esta guía explicará, con ejemplos prácticos y código real, cómo funcionan las APIs y por qué son esenciales en la vida digital actual.

Parte 1: ¿Qué es una API? La Analogía del Restaurante

Imagina que entras a un restaurante.

• Tú eres una aplicación (un cliente).
• El menú es la documentación de la API.
• El mesero es la API (Application Programming Interface).
• La cocina es el servidor (la aplicación que posee los datos o la funcionalidad).

¿Cómo funciona?

1. Haces una Petición (Request): lees el menú (documentación) y le dices al mesero (API) lo que quieres: “una hamburguesa con papas”.
2. La API procesa: el mesero lleva tu pedido a la cocina (servidor). Él sabe cómo comunicarse con los cocineros y qué formato usar.
3. Obtienes una Respuesta (Response): la cocina prepara la comida y el mesero (API) te la entrega. No ves el caos interno de la cocina; solo recibes el resultado final.

Definición técnica: Una API es un intermediario que permite que dos aplicaciones de software se comuniquen entre sí, siguiendo reglas y protocolos definidos.

// Ejemplo conceptual
// Cliente -> API -> Servidor
// Petición: “Dame los datos del clima”
// Respuesta: { temperatura: 22, ciudad: "Madrid" }
  

Parte 2: Los Tipos de APIs (Por Accesibilidad)

Las APIs pueden clasificarse según su nivel de acceso:

Parte 3: Estilos de Arquitectura de APIs (¿Cómo se Comunican?)

1. REST (Representational State Transfer)

REST es el estándar más utilizado. Se basa en los principios de la web y usa verbos HTTP para operar sobre recursos. Cada petición es independiente (stateless), y los datos viajan generalmente en formato JSON.

GET /users         // Obtener todos los usuarios
GET /users/123     // Obtener el usuario con ID 123
POST /users        // Crear un nuevo usuario
PUT /users/123     // Actualizar un usuario
DELETE /users/123  // Eliminar un usuario
  

2. SOAP (Simple Object Access Protocol)

SOAP es un protocolo más formal, basado en XML. Es ideal para entornos empresariales o financieros que requieren seguridad y control total.

3. GraphQL

Desarrollado por Facebook, GraphQL permite solicitar solo los datos necesarios, en una única petición. Esto evita el over-fetching y el under-fetching de información.

{
  user(id: "123") {
    name
    email
    posts(limit: 5) {
      title
    }
  }
}
  

Esta consulta obtiene el nombre, email y títulos de las últimas 5 publicaciones del usuario 123.

Parte 4: Ejemplos Reales que Todos Usamos

• El Tiempo en tu Móvil: apps como AccuWeather o tu widget del clima usan APIs REST como OpenWeatherMap.
• Login con Google o Facebook: utilizan APIs OAuth que validan tu identidad sin compartir tu contraseña.
• Pagos Online: tiendas y marketplaces usan APIs de Stripe o PayPal para procesar pagos seguros.
• Mapas Integrados: sitios de bienes raíces o delivery usan Google Maps API.
• Bots en Telegram o Discord: las plataformas ofrecen APIs públicas para crear bots automatizados.

Parte 5: Implementando un Manejador Profesional de APIs

En la práctica, los desarrolladores necesitan manejar errores, tiempos de espera y paginación. Aquí presentamos una clase moderna en JavaScript que cumple con esos requisitos:

class ManejadorAPI {
  constructor(baseURL, timeout = 8000) {
    this.baseURL = baseURL;
    this.timeout = timeout;
  }

  async solicitar(endpoint, opciones = {}) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
    
    const config = {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        ...opciones.headers
      },
      signal: controller.signal,
      ...opciones
    };

    try {
      const respuesta = await fetch(`${this.baseURL}${endpoint}`, config);
      clearTimeout(timeoutId);
      return await this._procesarRespuesta(respuesta);
    } catch (error) {
      clearTimeout(timeoutId);
      return this._manejarError(error);
    }
  }

  async _procesarRespuesta(respuesta) {
    const contentType = respuesta.headers.get('content-type');
    
    if (!respuesta.ok) {
      throw new Error(`HTTP Error: ${respuesta.status} - ${respuesta.statusText}`);
    }

    if (contentType && contentType.includes('application/json')) {
      return await respuesta.json();
    } else {
      return await respuesta.text();
    }
  }

  _manejarError(error) {
    if (error.name === 'AbortError') {
      throw new Error('Timeout: La solicitud tardó demasiado tiempo');
    } else if (error.name === 'TypeError') {
      throw new Error('Error de red: No se pudo conectar al servidor');
    } else {
      throw error;
    }
  }

  async obtenerDatosPaginados(endpoint, pagina = 1, limite = 10) {
    const datos = await this.solicitar(
      `${endpoint}?page=${pagina}&limit=${limite}`
    );
    
    return {
      datos: datos.items,
      paginacion: {
        paginaActual: pagina,
        totalPaginas: Math.ceil(datos.total / limite),
        totalElementos: datos.total,
        tieneSiguiente: pagina < Math.ceil(datos.total / limite),
        tieneAnterior: pagina > 1
      }
    };
  }
}

// Uso del manejador
const apiClima = new ManejadorAPI('https://api.openweathermap.org/data/2.5');

apiClima.obtenerDatosPaginados('/forecast', 2, 5)
  .then(resultado => {
    console.log('Datos:', resultado.datos);
    console.log('Info paginación:', resultado.paginacion);
  })
  .catch(error => {
    console.error('Error manejado:', error.message);
  });
  

Este manejador es ideal para proyectos que requieren robustez y escalabilidad en sus peticiones.

Parte 6: Consolidando Datos desde Múltiples APIs

En entornos empresariales es común combinar información de distintos proveedores. A continuación, un ejemplo que centraliza inventario de varias fuentes:

class GestorInventario {
  constructor() {
    this.proveedores = {
      proveedorA: 'https://api.proveedora.com/inventory',
      proveedorB: 'https://api.proveedorb.com/stock'
    };
  }

  async verificarDisponibilidad(productoId) {
    const disponibilidad = [];
    
    const consultas = Object.entries(this.proveedores).map(
      async ([nombre, url]) => {
        try {
          const respuesta = await fetch(`${url}/${productoId}`);
          const datos = await respuesta.json();
          
          disponibilidad.push({
            proveedor: nombre,
            stock: datos.stock,
            precio: datos.precio,
            tiempoEntrega: datos.tiempo_entrega
          });
        } catch (error) {
          console.error(`Error con ${nombre}:`, error);
        }
      }
    );
    
    await Promise.all(consultas);
    return disponibilidad;
  }
}

// Uso práctico
const gestor = new GestorInventario();
gestor.verificarDisponibilidad('PROD-123')
  .then(resultado => {
    console.log('Disponibilidad consolidada:', resultado);
  });
  

Conclusión y Llamada a la Acción

Las APIs son los bloques de construcción de la Internet moderna. Conectan servicios, automatizan procesos y permiten la innovación continua. Desde redes sociales hasta sistemas financieros, todo se basa en APIs bien diseñadas.

En próximos artículos exploraremos:

• Cómo hacer tu primera llamada a una API REST con JavaScript.
• REST vs GraphQL: ¿Cuál elegir para tu proyecto?
• Seguridad en APIs: Cómo proteger tus endpoints.

Autor: Benja — NewsBM Tech