Chapitre 11.7 — GraphQL (optionnel)

Partie 11 : API Platform — Chapitre 7/8 Version de référence : API Platform 4 / Symfony 7.4.

⏱️ TL;DR

• API Platform expose aussi vos resources en GraphQL, sans (presque) rien coder : on active le support, et #[ApiResource] génère queries, mutations et subscriptions.
• Endpoint /api/graphql + un playground GraphiQL pour explorer/tester.
• Les groupes de sérialisation, la validation et la sécurité (voters) s’appliquent comme en REST — vous ne redéclarez rien.
• GraphQL vs REST : GraphQL laisse le client choisir les champs et agréger en une requête (utile pour des UI riches/mobiles) ; REST est plus simple à cacher et à documenter.
• Côté Next.js : on consomme avec graphql-request, urql ou Apollo.
• Ce chapitre est optionnel : BookLab fonctionne très bien en REST. GraphQL est un plus si le front en tire parti.

🎯 Objectifs

• Activer GraphQL sur API Platform.
• Comprendre queries, mutations, subscriptions générées.
• Savoir quand GraphQL apporte quelque chose vs REST.
• Consommer GraphQL depuis Next.js.

1. Activer GraphQL

composer require api-platform/graphql

Aussitôt, vos resources #[ApiResource] sont exposées en GraphQL : un endpoint /api/graphql et un playground GraphiQL (sur /api/graphql/graphiql) pour construire et tester des requêtes interactivement.

2. Ce qui est généré

Pour chaque resource, API Platform crée automatiquement :

• Queries : récupérer un item (booking(id: ...)) ou une collection (bookings(...) avec pagination/filtres).
• Mutations : createBooking, updateBooking, deleteBooking.
• Subscriptions : recevoir des mises à jour en temps réel (couplées à Mercure, Partie 12).

Une requête GraphQL typique (le client choisit les champs) :

query {
  bookings(first: 10, status: "confirmed") {
    edges {
      node {
        id
        customerEmail
        status
        slot { start service { name } }   # on imbrique ce dont on a besoin, en une requête
      }
    }
  }
}

Le client demande exactement les champs voulus, y compris à travers les relations, en une seule requête — l’atout signature de GraphQL.

3. Groupes, validation, sécurité : réutilisés

Vous ne redéclarez rien : GraphQL réutilise vos groupes de sérialisation (chapitre 11.2), votre validation (11.4) et votre sécurité (11.5). On peut toutefois définir des groupes/security spécifiques à GraphQL par opération si besoin :

use ApiPlatform\GraphQl\Metadata\{Query, Mutation};
 
#[ApiResource(
    graphQlOperations: [
        new Query(security: "is_granted('VIEW', object)"),
        new Mutation(name: 'create', security: "is_granted('ROLE_USER')"),
    ],
)]
class Booking { /* ... */ }

4. GraphQL vs REST : quand quoi

Règle : REST par défaut (simple, cacheable, doc OpenAPI → types TS). GraphQL si le front bénéficie vraiment du choix de champs et de l’agrégation (UI très variées, mobile économe en bande passante, dashboards composant plusieurs sources). Les deux peuvent coexister sur la même base de resources.

⚠️ Piège : adopter GraphQL « parce que c’est moderne » ajoute un client GraphQL, complique le cache et la sécurité par requête (requêtes profondes/coûteuses à limiter). Si votre front consomme des vues fixes, REST + génération de types TS est plus simple et tout aussi typé. Choisissez selon le besoin réel du front, pas la hype.

5. Consommer depuis Next.js

Côté front, on utilise un client GraphQL :

// avec graphql-request (léger)
import { request, gql } from 'graphql-request';
 
const query = gql`
  query Bookings {
    bookings(first: 10) {
      edges { node { id customerEmail status } }
    }
  }
`;
 
const data = await request(`${process.env.API_URL}/api/graphql`, query, {}, {
  Authorization: `Bearer ${token}`,
});

Pour des besoins riches (cache normalisé, optimistic UI), urql ou Apollo Client ; le schéma GraphQL permet aussi de générer des hooks typés (graphql-codegen), l’équivalent GraphQL de la génération de types depuis OpenAPI.

💡 Pour un dev Next.js : si vous avez déjà utilisé Apollo/urql, vous êtes à l’aise. L’avantage du couple API Platform GraphQL + Next.js : vous n’écrivez ni le schéma ni les resolvers — ils dérivent de vos #[ApiResource]. Vous vous concentrez sur les requêtes côté front. Pour BookLab, on garde REST comme socle (chapitre 11.8) et GraphQL reste une corde en plus.

✏️ Exercices

Exercice 1. Écrivez une requête GraphQL qui récupère les 5 premières réservations avec leur email et le nom du service (via slot → service).

query {
  bookings(first: 5) {
    edges {
      node {
        customerEmail
        slot { service { name } }
      }
    }
  }
}

Exercice 2. Faut-il redéfinir la validation et la sécurité pour GraphQL ?

Exercice 3. Dans quel cas GraphQL apporte-t-il un vrai gain par rapport à REST pour BookLab ?

🧠 Quiz de révision

Prochain chapitre : 11.8 — Consommer l’API dans Next.js ⭐ — le chapitre phare : fetch, JWT, RSC/SSR, mutations et revalidation.