Chapitre 9.4 — WPGraphQL

⏱️ TL;DR — WPGraphQL est un plugin (non natif) qui expose WordPress via une API GraphQL sur un endpoint unique /graphql. Avantage majeur pour un front moderne : vous demandez exactement les champs voulus, y compris les ressources liées (auteur, image, taxonomies, meta) en une seule requête — fini le sur-fetching et les allers-retours _embed de REST. Il s’intègre parfaitement avec Next.js/Apollo/urql. Le choix REST vs GraphQL dépend du projet ; GraphQL brille sur les fronts headless riches.

🎯 Objectifs

• Comprendre ce qu’apporte GraphQL vs REST pour WordPress.
• Écrire une requête GraphQL de base.
• Connaître l’écosystème (WPGraphQL + extensions).
• Choisir entre REST et GraphQL selon le contexte.

1. GraphQL en une image

REST expose plusieurs routes, chacune renvoyant un payload figé. GraphQL expose un endpoint où le client décrit la donnée voulue :

• REST : plusieurs requêtes (ou _embed), champs imposés (sur-fetching).
• GraphQL : une requête, champs exacts, ressources liées incluses.

2. Une requête WPGraphQL

Après installation du plugin WPGraphQL, l’endpoint /graphql (et l’IDE GraphiQL dans l’admin) est disponible.

query DerniersLivres {
  livres(first: 5, where: { orderby: { field: DATE, order: DESC } }) {
    nodes {
      id
      title
      slug
      featuredImage { node { sourceUrl altText } }
      # meta exposée via une extension / registerGraphQLField
    }
  }
}

Réponse : exactement id, title, slug, l’URL de l’image — rien de plus. Le front reçoit un payload taillé à son besoin.

⚠️ Piège — le CPT/la meta absents de GraphQL. Comme pour REST (show_in_rest), un CPT doit être exposé à GraphQL : à l’enregistrement, show_in_graphql => true + graphql_single_name/graphql_plural_name (options ajoutées par WPGraphQL). Les meta doivent être déclarées via register_graphql_field(). Sans ça, elles n’apparaissent pas dans le schéma.

3. L’écosystème

• WPGraphQL (le cœur) : expose posts, pages, CPT, taxonomies, menus, users, réglages.
• Extensions : WPGraphQL for ACF (champs ACF), WPGraphQL for WooCommerce (WooGraphQL), etc.
• WPGraphQL Smart Cache : mise en cache/invalidation, essentielle en production.
• Côté front : Apollo Client, urql, ou un simple fetch POST — tous compatibles Next.js. Des outils génèrent les types TypeScript depuis le schéma (GraphQL Code Generator).

💡 Pour un dev React — Si vous venez d’Apollo/urql/GraphQL Code Generator, WPGraphQL vous met en terrain connu : un schéma typé, des requêtes précises, la génération de types TS, l’intégration Next.js. C’est souvent l’expérience la plus agréable pour un front headless riche — WordPress devient une simple source de données GraphQL, comme n’importe quel back GraphQL.

4. REST ou GraphQL ? (décision)

Repères :

• REST : suffit pour des besoins simples, pas de dépendance à ajouter, endpoints custom faciles (ch. 9.3). Bon défaut.
• WPGraphQL : front riche avec beaucoup de relations, équipe habituée à GraphQL, besoin de payloads précis et de types générés. Excellent pour un gros projet headless.

⚠️ Piège — GraphQL « par principe ». Ajouter WPGraphQL sur un petit site où REST suffit, c’est une dépendance de plus à maintenir (mises à jour, cache, sécurité) pour peu de gain. Choisissez selon la complexité réelle du front, pas par mode.

5. Sécurité et performance (rappels)

• Auth : mêmes principes qu’en REST (ch. 9.2) — WPGraphQL supporte cookie+nonce, Application Passwords, JWT (extension). Secrets côté serveur en headless.
• Requêtes coûteuses : GraphQL permet des requêtes profondes/imbriquées potentiellement lourdes → limiter la profondeur/complexité, cacher (Smart Cache), paginer.
• Exposition : ne rendez visibles au schéma que les données voulues (comme show_in_rest).

✏️ Exercices

1. Citez le principal avantage de GraphQL sur REST pour un front headless riche.
2. Votre CPT livre n’apparaît pas dans le schéma GraphQL. Que manque-t-il ?
3. Sur un petit site vitrine headless simple, REST natif ou WPGraphQL ? Pourquoi ?

🧠 Quiz de révision

Chapitre suivant : WordPress headless avec Next.js.