WordPress GraphQL API 2025 | Headless con JWT

Introducción: La Evolución de WordPress como Backend Moderno

Durante más de una década, WordPress ha sido el rey indiscutible de los sistemas de gestión de contenidos (CMS) tradicionales, alimentando desde blogs personales hasta portales empresariales. Sin embargo, el paradigma del desarrollo web ha cambiado. Hoy, los desarrolladores buscan separar la capa de presentación (frontend) de la lógica de gestión de contenidos (backend). Es aquí donde surge el concepto de API headless WordPress.

En lugar de renderizar HTML en el servidor, WordPress se convierte en un repositorio de contenido puro, expuesto a través de una API. Al combinarlo con GraphQL y autenticación JWT (JSON Web Tokens), obtenemos una arquitectura moderna, segura y extremadamente flexible. Este artículo explora en profundidad cómo configurar WordPress como una API headless, implementar GraphQL como lenguaje de consulta y asegurar las peticiones con JWT.

¿Por qué usar WordPress como API Headless?

La arquitectura headless desacopla el frontend del backend. En lugar de que WordPress genere páginas HTML completas, solo expone datos estructurados (JSON) a través de una API. El frontend (React, Vue, Angular, Next.js, etc.) consume esos datos y los presenta al usuario.

Ventajas clave:

Rendimiento mejorado: El frontend puede servirse desde un CDN estático, mientras WordPress se ejecuta en un servidor optimizado para backend.
Experiencia de usuario superior: Frameworks como React permiten transiciones suaves, actualizaciones parciales y carga progresiva.
Seguridad: Al no exponer el panel de administración ni los temas de WordPress, se reduce la superficie de ataque.
Reutilización de contenido: El mismo contenido puede servir a una web, una app móvil, un asistente de voz o un IoT.
Escalabilidad: El frontend y el backend pueden escalar de forma independiente.

[INFO] La API REST de WordPress (WP REST API) ya permite cierto nivel headless, pero GraphQL ofrece una eficiencia muy superior al permitir consultas exactas sin sobresuscripción de datos.

Implementando GraphQL en WordPress

WordPress GraphQL se implementa típicamente mediante el plugin WPGraphQL. Este plugin expone un endpoint GraphQL completo, permitiendo consultar entradas, páginas, usuarios, comentarios, taxonomías y campos personalizados (ACF, Meta Box, etc.) con una sintaxis declarativa.

Instalación y configuración básica

Instala el plugin WPGraphQL desde el repositorio oficial o mediante Composer:
```
composer require wp-graphql/wp-graphql
```
Actívalo desde el panel de administración.
Verifica el endpoint: https://tudominio.com/graphql. Deberías poder acceder a la interfaz GraphiQL (si está habilitada) o al menos recibir una respuesta JSON.

Primeras consultas

Una vez instalado, puedes hacer consultas como esta:

{
  posts(first: 5) {
    nodes {
      title
      slug
      date
      featuredImage {
        node {
          sourceUrl
        }
      }
    }
  }
}

Esto devuelve exactamente los campos solicitados, sin datos extra. Si además usas ACF con WPGraphQL (plugin wpgraphql-acf), puedes consultar campos personalizados:

{
  page(id: "about-us", idType: URI) {
    title
    acfFields {
      heroTitle
      heroDescription
    }
  }
}

[TIP] Para entornos de producción, deshabilita GraphiQL y limita los métodos HTTP permitidos. Usa un plugin de seguridad como WAF o una API Gateway.

Autenticación JWT en WordPress

La autenticación WordPress tradicional basada en cookies no es adecuada para APIs headless, especialmente cuando el frontend está en un dominio diferente o es una app móvil. JWT (JSON Web Tokens) resuelve esto: un token firmado que contiene la identidad del usuario y expira tras un tiempo definido.

Instalación del plugin JWT Authentication

Recomendamos el plugin JWT Authentication for WP-API (o su variante Firebase JWT Auth). Sigue estos pasos:

Instala y activa el plugin desde el repositorio.
Agrega las siguientes constantes a tu archivo wp-config.php:
```
define('JWT_AUTH_SECRET_KEY', 'tu-clave-secreta-muy-larga-y-aleatoria');
define('JWT_AUTH_CORS_ENABLE', true);
```
La clave secreta debe generarse con un generador criptográfico (ej: openssl rand -base64 64).

Configura CORS si tu frontend está en otro dominio. Puedes usar el plugin WP CORS o agregar headers manualmente:

add_action('rest_api_init', function() {
    remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
    add_filter('rest_pre_serve_request', function($value) {
        header('Access-Control-Allow-Origin: https://tudominio-frontend.com');
        header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
        header('Access-Control-Allow-Headers: Authorization, Content-Type');
        return $value;
    });
});

Flujo de autenticación con JWT

Obtener token: El frontend envía credenciales (usuario y contraseña) al endpoint /wp-json/jwt-auth/v1/token.
Validar token: Cada petición a la API incluye el token en el header Authorization: Bearer <token>.
Refrescar token: Cuando expira, se usa el endpoint /wp-json/jwt-auth/v1/token/refresh.

Ejemplo de solicitud desde JavaScript:

// Login
const login = async (username, password) => {
  const response = await fetch('https://tudominio.com/wp-json/jwt-auth/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  const data = await response.json();
  localStorage.setItem('token', data.token);
};

// Petición autenticada
const fetchPosts = async () => {
  const token = localStorage.getItem('token');
  const response = await fetch('https://tudominio.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ query: '{ posts { nodes { title } } }' })
  });
  return response.json();
};

[WARNING] Nunca almacenes el token JWT en localStorage si tu sitio es vulnerable a XSS. Considera usar httpOnly cookies con un proxy backend o almacenamiento en memoria para apps críticas.

Integración Completa: GraphQL + JWT

Cuando combinas GraphQL WordPress con JWT WordPress, obtienes un backend headless completamente funcional y seguro. El flujo típico es:

Login: El usuario se autentica y recibe un JWT.
Consulta autenticada: El frontend envía el JWT en el header Authorization al endpoint GraphQL.
WPGraphQL verifica el token y permite acceso a datos privados (borradores, usuarios, contenido restringido por roles).

Configuración de permisos en WPGraphQL

WPGraphQL respeta los permisos de WordPress. Si un usuario no tiene permiso para ver ciertos contenidos, la consulta fallará o devolverá null. Para habilitar consultas públicas (sin autenticación) para contenido público, debes configurar el plugin:

En Ajustes > WPGraphQL, marca la opción "Public Introspection" si deseas que cualquiera pueda explorar el esquema.
Para contenido privado, el token JWT debe pertenecer a un usuario con los roles adecuados.

Casos de Uso Avanzados

1. Aplicaciones en Tiempo Real con WebSockets

Aunque GraphQL es principalmente síncrono, puedes combinarlo con WebSockets usando GraphQL Subscriptions. Para ello, necesitas un servidor Node.js que actúe como proxy entre el frontend y WordPress, utilizando la API REST de WordPress como fuente de datos.

2. Headless Multisitio

WordPress Multisite puede exponer un único endpoint GraphQL que unifique el contenido de todos los sitios. WPGraphQL soporta multisitio de forma nativa, permitiendo consultas como:

{
  sites {
    nodes {
      name
      posts {
        nodes {
          title
        }
      }
    }
  }
}

3. Integración con Gatsby o Next.js

Frameworks como Gatsby o Next.js pueden pre-renderizar páginas usando datos de WordPress GraphQL en tiempo de compilación. Para contenido dinámico, se usa SSR (Server-Side Rendering) con autenticación JWT.

// Next.js API route
export default async function handler(req, res) {
  const token = req.headers.authorization?.split(' ')[1];
  const response = await fetch('https://tudominio.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ query: '...' })
  });
  const data = await response.json();
  res.status(200).json(data);
}

Consideraciones de Seguridad y Rendimiento

Seguridad

Usa HTTPS en todas las comunicaciones.
Rota las claves JWT periódicamente.
Implementa rate limiting en el endpoint GraphQL y JWT.
Valida entradas en el frontend y backend (especialmente en mutaciones).

Rendimiento

Cachea las consultas GraphQL con plugins como WPGraphQL Cache o un CDN que soporte GraphQL.
Limita la profundidad de las consultas para evitar ataques de recursión.
Usa paginación con first, after, last, before en lugar de traer todos los datos.

[TIP] Para consultas públicas, considera usar un plugin de caché de página estática (como WP Rocket o Litespeed Cache) que almacene las respuestas GraphQL en caché.

Conclusión

Adoptar WordPress como API headless con GraphQL y autenticación JWT no es solo una tendencia, sino una necesidad para proyectos que requieren rendimiento, escalabilidad y experiencias de usuario modernas. La combinación de la robustez de WordPress como CMS, la eficiencia de GraphQL y la seguridad de JWT permite construir aplicaciones web y móviles de alto nivel sin perder la facilidad de gestión que ofrece WordPress.

El ecosistema de plugins (WPGraphQL, JWT Authentication, ACF para GraphQL) ha madurado lo suficiente como para que esta arquitectura sea viable en producción. Ya sea que estés migrando un sitio existente o empezando un proyecto desde cero, esta pila tecnológica te dará la flexibilidad que necesitas para el futuro.

Ahora es el momento de experimentar: instala los plugins, escribe tus primeras consultas GraphQL y prueba el flujo de autenticación JWT. Tu próximo proyecto headless te lo agradecerá.