Cómo usar GraphQL con WPGraphQL

Introducción a GraphQL y WPGraphQL

En la evolución de las APIs, GraphQL ha demostrado ser una alternativa poderosa a REST, permitiendo a los clientes solicitar exactamente los datos que necesitan. WPGraphQL es un plugin de WordPress que expone un endpoint GraphQL, integrando sin fisuras la flexibilidad de GraphQL con el ecosistema de WordPress.

En este artículo detallado y extenso, exploraremos:

• Conceptos básicos de GraphQL y su comparación con REST.
• Requisitos y configuración de WPGraphQL.
• Autenticación y seguridad.
• Ejemplos de consultas y mutaciones.
• Extensión del esquema: tipos personalizados y campos avanzados.
• Buenas prácticas de rendimiento y herramientas útiles.

1. ¿Por qué elegir GraphQL sobre REST

La arquitectura REST ha sido la elección predominante durante años. Sin embargo, presenta limitaciones:

Característica	REST	GraphQL
Overfetching	Frecuente	Evitable
Underfetching	Necesita múltiples endpoints	Todo en una sola petición
Versionado de API	Gestión compleja	Evolucionable sin versiones

GraphQL permite definir un único endpoint donde el cliente describe la forma de los datos. Esto simplifica el mantenimiento, optimiza el rendimiento y brinda mayor control al consumidor de la API.

2. Requisitos y Arquitectura de WPGraphQL

Antes de comenzar, asegúrate de contar con:

• WordPress 5.0 o superior.
• PHP 7.2 y MySQL 5.6 o MariaDB equivalente.
• Permisos de administrador en tu sitio WordPress.

WPGraphQL es un plugin gratuito de código abierto mantenido por la comunidad y disponible en GitHub y en el repositorio oficial de WordPress:
https://github.com/wp-graphql/wp-graphql

En cuanto a la arquitectura, WPGraphQL:

• Expone un endpoint /graphql.
• Utiliza el motor de GraphQL de Facebook adaptado a PHP.
• Extiende el core de WordPress para registrar tipos, campos y resolvers.

2.1 Instalación del plugin

1. Accede al panel de administración de WordPress.
2. Ve a Plugins gt Añadir nuevo.
3. Busca “WPGraphQL” e instálalo.
4. Activa el plugin.

Tras la activación, tu sitio tendrá disponible el endpoint https://tusitio.com/graphql.

2.2 Herramientas de prueba

• GraphiQL IDE integrado: accede a /graphql-explorer.
• Insomnia o Postman, configurados con método POST y payload en JSON.

3. Autenticación y Seguridad

De forma predeterminada, las consultas públicas (por ejemplo, obtener posts públicos) funcionan sin autenticación. Para operaciones protegidas (mutations, datos privados), podemos emplear:

• Cookies de sesión de WordPress: útil para front-ends que viven dentro de WordPress.
• JWT Authentication for WP-API: plugin que expone tokens JWT (enlace oficial).
• OAuth2: mediante plugins como “WP OAuth Server”.

Además, es fundamental:

• Limitar la profundidad y complejidad de consultas (query complexity).
• Desactivar introspección en producción si es necesario.
• Registrar roles y capacidades de WordPress para restringir campos sensibles.

4. Ejemplos Prácticos de Consultas (Queries)

Veamos ejemplos típicos:

4.1 Consulta básica de posts

{
  posts(first: 5) {
    nodes {
      id
      title
      date
      author {
        node {
          name
        }
      }
    }
  }
}

Resultado esperado:

• id: identificador único.
• title: título del post.
• date: fecha de publicación en formato ISO.
• author.name: nombre del autor.

4.2 Filtrado y paginación

{
  posts(where: { categoryName: Noticias }, first: 10, after: Y3Vyc29yOnYyOpHOAA==) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      title
      excerpt
    }
  }
}

Podemos controlar la paginación con first/last y after/before, empleando Relay Cursor Connections.

5. Mutations: Crear y Actualizar Contenido

WPGraphQL permite realizar mutations para crear, actualizar o eliminar datos. Veamos un ejemplo de creación de post:

mutation CreatePost {
  createPost(input: {
    title: Nuevo Post GraphQL
    content: Contenido del post creado via GraphQL
    status: PUBLISH
  }) {
    post {
      id
      title
      status
    }
  }
}

El campo status puede ser DRAFT, PUBLISH o PRIVATE. Para ejecutar mutations autenticadas, debemos enviar el token JWT o la cookie de WordPress.

6. Extender el Esquema de WPGraphQL

Gran parte de la potencia de WPGraphQL radica en su capacidad de extender el esquema para adaptarse a necesidades específicas.

6.1 Registrar un campo personalizado

Supongamos que cada Post tiene un campo meta rating. Podemos exponerlo así:

add_action(graphql_register_types, function() {
  register_graphql_field(Post, rating, [
    type => Int,
    description => Valoración del post,
    resolve => function(post) {
      return (int) get_post_meta(post->ID, rating, true)
    }
  ])
})

6.2 Crear un tipo de objeto personalizado

Imagina una entidad “Serie”. Podríamos:

add_action(graphql_register_types, function() {
  register_graphql_object_type(Serie, [
    description => Una serie de artículos relacionados,
    fields => [
      id => [type => ID],
      title => [type => String],
      episodes => [
        type => [list_of => Episode],
        resolve => get_serie_episodes
      ]
    ]
  ])
})

Luego registraríamos get_serie_episodes para devolver una lista de episodios.

7. Rendimiento y Cache

Para sitios con alto tráfico, tener en cuenta:

• Persistent Queries: predefinir consultas y servirlas por hash.
• DataLoader: agrupar solicitudes para evitar N 1 queries.
• Cache de objetos: usar transients o plugins de cache de GraphQL (Apollo Cache Redis).

8. Herramientas y Buenas Prácticas

8.1 GraphiQL y Altair

• GraphiQL integrado en WPGraphQL: ideal para desarrollo y pruebas.
• Altair y Postwoman: extensiones de navegador que ofrecen testing avanzado.

8.2 Generación de Código

Con GraphQL Code Generator (sitio oficial), podemos generar definiciones de TypeScript o clases PHP a partir del esquema.

8.3 Control de Versiones del Esquema

• Almacenar el esquema en formato SDL (.graphql).
• Revisiones en Git para cambios en tipos y campos.

Conclusión

WPGraphQL abre un abanico de posibilidades para desarrollo de front-ends modernos (React, Vue, Svelte) o aplicaciones móviles, ofreciendo consultas precisas y mutaciones seguras. La combinación de WordPress como CMS robusto con GraphQL como capa de datos flexible permite arquitecturas headless y experiencias de usuario de alto rendimiento.

Te animamos a explorar más en la documentación oficial:
https://www.wpgraphql.com/

¡Empieza hoy mismo a potenciar tus proyectos WordPress con GraphQL!