PHP Academy · Leçon

GraphQL ou REST

Comprenez quand GraphQL est préférable à REST et pourquoi.

GraphQL ou REST est une leçon PHP Academy gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage PHP Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours PHP Academy comprend 4 leçons au total.

Pourquoi GraphQL ?

Vous savez déjà déployer des API REST en PHP. GraphQL ne remplace ni HTTP ni une solution miracle : c'est un langage de requête et un système de types qui permet au client de décrire précisément ce dont il a besoin et d'obtenir exactement cela, en un seul aller-retour.

Dans cette leçon, nous comparons honnêtement les deux : les domaines où GraphQL est réellement meilleur, ceux où REST reste le choix approprié et le coût opérationnel de GraphQL.

Récupération excessive et insuffisante

Les points faibles classiques de REST :

Récupération excessive : GET /users/1 renvoie 40 champs alors que l'interface utilisateur n'en nécessite que 3.
Récupération insuffisante : pour afficher les publications d'un utilisateur et le nombre de commentaires de chaque publication, vous appelez /users/1, puis /users/1/posts, puis N points de terminaison de commentaires.

GraphQL réduit tout cela à une seule requête déclarative.

query {
  user(id: 1) {
    name
    posts {
      title
      commentCount
    }
  }
}

Un point de terminaison, un schéma typé

REST expose de nombreuses URL ; GraphQL expose un seul point de terminaison (généralement POST /graphql) reposant sur un schéma fortement typé. Le schéma constitue le contrat : il peut être inspecté, si bien que les outils (complétion automatique, documentation, génération de code) sont disponibles gratuitement.

Voici un schéma minimal en SDL. La structure de toute réponse possible est connue à l'avance.

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  commentCount: Int!
}

type Query {
  user(id: ID!): User
}

La réponse reflète la requête

Une propriété essentielle : la structure de la réponse JSON est prévisible à partir de la requête. Les clients n'ont jamais à deviner les noms des champs. Cela élimine toute une catégorie de changements liés au versionnage : vous ajoutez des champs sans interrompre les anciens clients et marquez les champs comme obsolètes avec @deprecated au lieu de supprimer les URL /v2.

{
  "data": {
    "user": {
      "name": "Ada",
      "posts": [
        { "title": "On Engines", "commentCount": 12 }
      ]
    }
  }
}

Quand GraphQL est préférable à REST

GraphQL est le meilleur choix lorsque :

Vous servez de nombreux clients hétérogènes (web, iOS, Android) ayant des besoins différents en matière de données.
Les données forment un graphe avec des relations profondes que les clients parcourent dynamiquement.
Vous souhaitez agréger plusieurs services en aval derrière une passerelle typée.
Les itérations rapides de l'interface sont importantes et vous voulez éviter les modifications incessantes des points de terminaison des services.

Quand REST reste le meilleur choix

Ne choisissez pas GraphQL par réflexe. REST est plus simple et souvent préférable lorsque :

Vous avez besoin de mise en cache HTTP — les caches CDN et périphériques s'appuient sur les URL et les verbes ; un unique POST /graphql leur est opaque.
L'API est orientée ressources et stable (CRUD sur quelques entités).
Vous utilisez des téléversements/téléchargements de fichiers ou de la diffusion en flux, pour lesquels le multipart et les plages d'octets sont pris en charge nativement par REST.
Vos consommateurs sont des tiers qui s'attendent à une sémantique REST conventionnelle.

Brève comparaison en PHP

Voici les mêmes données assemblées selon l'approche REST en PHP — remarquez que le client aurait toujours besoin de plusieurs appels, ou que vous devriez créer vous-même un paramètre d'inclusion. GraphQL déplace plutôt cette logique de sélection vers le client.

<?php
// REST: server decides the payload shape
function userResource(int $id): array {
    return [
        'id' => $id,
        'name' => 'Ada',
        'email' => 'ada@example.com',   // over-fetched by mobile
        'createdAt' => '1815-12-10',
        'posts' => [                       // pre-embedded, all-or-nothing
            ['title' => 'On Engines', 'commentCount' => 12],
        ],
    ];
}

header('Content-Type: application/json');
echo json_encode(userResource(1), JSON_PRETTY_PRINT);

Les coûts ajoutés par GraphQL

GraphQL déplace la complexité vers le serveur. Vous devez désormais prendre en charge les aspects suivants :

Requêtes N+1 — les résolveurs imbriqués déclenchent une requête de base de données par nœud, sauf si vous les regroupez (DataLoader).
Limitation du coût et de la profondeur des requêtes — une requête malveillante profondément imbriquée peut provoquer un déni de service.
La mise en cache est plus difficile ; vous mettez généralement en cache au niveau du résolveur ou des données, et non au niveau HTTP.
La gestion des erreurs est différente — un 200 OK peut tout de même contenir un tableau errors.

Erreurs : 200 avec un tableau d'erreurs

Contrairement aux codes d'état REST, GraphQL renvoie généralement le code HTTP 200 et signale les échecs partiels dans le corps de la réponse. data peut être partiellement rempli tandis que errors répertorie les éléments ayant échoué. Vos clients doivent examiner les deux.

{
  "data": { "user": null },
  "errors": [
    {
      "message": "User not found",
      "path": ["user"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

Repère pour décider

Une règle pratique :

API publiques, fortement mises en cache, avec un CRUD orienté ressources → REST.
API internes ou de produit qui alimentent des clients riches et variés sur des données interconnectées → GraphQL.
Nombreux services dorsaux à unifier derrière un contrat typé → passerelle GraphQL.

Il est courant et sain d'utiliser les deux : REST pour les webhooks et les téléversements, GraphQL pour le graphe de lecture de l'application.

Exposer GraphQL via HTTP en PHP

En pratique, un point d'accès GraphQL en PHP est une route qui lit le corps JSON, extrait query et variables, les exécute sur le schéma et renvoie { data, errors }. Par rapport aux nombreuses routes de REST, le transport est uniforme : toute la variation se trouve dans la chaîne de requête envoyée par le client.

<?php
// Minimal GraphQL-over-HTTP entry point
$input = json_decode(file_get_contents('php://input'), true) ?? [];
$query = $input['query'] ?? '';
$variables = $input['variables'] ?? null;

// $result = GraphQL::executeQuery($schema, $query, null, $ctx, $variables);
// header('Content-Type: application/json');
// echo json_encode($result->toArray());
var_dump(['query' => $query, 'variables' => $variables]);

Vérification rapide

Dans quels cas REST conserve-t-il un avantage net sur GraphQL ?

Récapitulatif

Vous avez comparé GraphQL et REST sur le fond :

GraphQL résout les problèmes de récupération excessive ou insuffisante grâce à un unique point d'accès typé et à une sélection pilotée par le client.
Il est particulièrement adapté à de nombreux clients, aux données structurées en graphe et à l'agrégation de services dorsaux.
REST reste un excellent choix pour les API publiques pouvant être mises en cache, le CRUD simple, les téléversements et les consommateurs conventionnels.
GraphQL reporte les coûts sur le serveur : N+1, limites de coût des requêtes, mise en cache et sémantique « 200 avec erreurs ».

Ensuite : construire réellement un schéma avec webonyx/graphql-php.

Questions Fréquemment Posées

La leçon « GraphQL ou REST » est-elle gratuite ?

Oui — le texte complet de « GraphQL ou REST » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours PHP Academy, passe à CoddyKit PRO. Le cours PHP Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « GraphQL ou REST » ?

Comprenez quand GraphQL est préférable à REST et pourquoi. Tu pratiques PHP Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer PHP Academy ?

Aucune expérience préalable n'est requise. PHP Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.

Combien de temps prend la leçon « GraphQL ou REST » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon PHP Academy ?

Oui. Chaque leçon PHP Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à PHP Academy