APIs externas en tu web: guía completa de integración REST, GraphQL y Webhooks

APIs externas en tu web: guía completa de integración REST, GraphQL y Webhooks

Cada web moderna conecta con servicios externos: pasarelas de pago, CRMs, herramientas de email marketing, sistemas de mapas, redes sociales. Sin estas integraciones, tu web es una isla. Con ellas, se convierte en un ecosistema.

Si quieres profundizar en el flujo completo, consulta nuestra guía completa de integración de APIs y el post sobre errores comunes en integración de APIs REST.

¿Qué es una API y cómo funciona?

Una API (Application Programming Interface) es un contrato: le pides datos en un formato concreto y te devuelve una respuesta estructurada. Las más comunes en web son las APIs REST, que usan el protocolo HTTP estándar.

Ejemplo práctico: consultar el tiempo en Valencia desde OpenWeatherMap:

const respuesta = await fetch(
  "https://api.openweathermap.org/data/2.5/weather?q=Valencia,ES&appid=TU_API_KEY"
);
const datos = await respuesta.json();

La web pide, la API responde. Así de simple.

REST vs GraphQL: ¿cuál elegir?

REST: el estándar universal

• Funciona así: cada endpoint tiene una URL específica (/users, /orders/123)
• Ventajas: simple, cacheable, ampliamente soportado
• Inconvenientes: puede generar sobrefetch (pedir datos de más) o underfetch (pedir datos de menos)

GraphQL: la consulta precisa

• Funciona así: una sola URL (/graphql) acepta consultas específicas
• Ventajas: pides exactamente lo que necesitas, un solo request para muchos datos
• Inconvenientes: mayor complejidad, caching más difícil

Regla práctica: si tu web consume datos de 3 o más servicios diferentes, GraphQL puede simplificar mucho. Si solo conectas con 1 o 2 APIs, REST suele ser más rápido de implementar.

Webhooks: cuando la API te llama a ti

Los webhooks son el inverso del modelo típico de API. En lugar de pedir datos cada X minutos (polling), el servicio externo te avisa cuando ocurre algo.

Ejemplo: cuando un cliente paga en Stripe, Stripe envía un POST a tu web automáticamente:

app.post("/webhooks/stripe", (req, res) => {
  const evento = req.body;

  if (evento.type === "payment_intent.succeeded") {
    actualizarPedido(evento.data.object.metadata.order_id);
  }

  res.json({ received: true });
});

Errores comunes en integraciones de APIs

1. No manejar errores de red

Las APIs fallan. Siempre. Tu código debe contemplar timeouts, respuestas 500 y conexiones perdidas:

async function llamarAPI(url) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 5000);

  try {
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(timeoutId);

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    clearTimeout(timeoutId);
    console.error("API fallida:", error.message);
    return obtenerCache(url);
  }
}

2. Exponer credenciales en el frontend

Nunca pongas API keys en código que se ejecuta en el navegador. Un atacante abre DevTools y las roba.

Correcto: la API key vive en tu servidor backend, que hace de proxy: Frontend → Backend (con la clave) → API externa.

3. No validar la respuesta

Asumir que la API siempre devuelve el formato esperado es peligroso. Valida siempre:

const datos = await fetchWeather(city);

if (!datos?.main?.temp) {
  throw new Error("Formato inesperado de la API de tiempo");
}

Checklist de integración de APIs

• API key en variable de entorno, nunca en código público
• Timeouts configurados (máximo 5-10 segundos)
• Reintentos automáticos con backoff exponencial
• Fallback cuando la API no responde
• Logs de las llamadas para depuración
• Rate limiting respetado
• Verificación de firma en webhooks (evita spoofing)

Servicios externos que muchas webs conectan

Depende de tu negocio, pero estas integraciones son frecuentes:

¿Necesitas ayuda con tus integraciones?

Si tu web necesita conectar con servicios externos y no tienes tiempo o conocimiento técnico, en Artemis Code desarrollamos integraciones robustas con gestión de errores, reintentos y monitorización.

Contacta con nosotros y te ayudamos a conectar tu proyecto con el ecosistema que necesita.

¿Ya usas alguna integración por API en tu web? Comparte tu experiencia con la comunidad en LinkedIn.