Drupal comme backend : GraphQL, JSON:API, RESTful et l’erreur coûteuse cachée dans le choix de l’API

Un jour, un CTO m’a demandé, au milieu d’une réunion de planification d’un Drupal découplé : « Alors, quelle API devrions-nous utiliser ? »

La salle est restée silencieuse pendant une seconde. Le frontend voulait GraphQL. Le backend voulait JSON:API. Un fournisseur d’intégration avait déjà supposé REST. Le product owner voulait simplement que l’application mobile cesse d’attendre les releases du site web.

Cette petite question semble généralement technique. Elle ne l’est pas. C’est une question de gouvernance, une question de budget et parfois une question de recrutement déguisée en hoodie de développeur.

Drupal peut être un backend très performant pour des produits découplés. Il dispose déjà de contenu structuré, de rôles, de permissions, de workflows, de révisions, de traductions, de gestion des médias, de taxonomie et d’un écosystème de modules mature. La partie délicate consiste à décider comment ce contenu sort de Drupal. Le cœur de Drupal prend nativement en charge JSON:API, GraphQL est disponible via un module contribué, et le module RESTful Web Services de Drupal reste une option pour des endpoints personnalisés de type ressource. La propre documentation de Drupal sur le découplage présente clairement la séparation : JSON:API est dans le cœur, GraphQL est contribué, et Drupal peut exposer du contenu à un frontend externe via des APIs.

Et pourtant, les équipes continuent à faire de mauvais choix.

Elles choisissent GraphQL parce que cela semble moderne. Elles choisissent REST parce que tout le monde l’a déjà utilisé. Elles choisissent JSON:API parce qu’il est là. Aucune de ces raisons n’est une stratégie.

Voici la version plus directe : pour la plupart des plateformes de contenu adossées à Drupal, JSON:API devrait être le point de départ par défaut. GraphQL devrait se mériter. REST devrait être réservé aux cas où les deux autres options sont trop larges ou trop prescriptives.

Cela va agacer certaines personnes. Tant mieux.

Commencez par le gagnant ennuyeux : JSON:API

JSON:API est ennuyeux de la meilleure manière possible.

Le module JSON:API du cœur de Drupal implémente la spécification JSON:API pour les entités Drupal. Il fournit une manière sans configuration, prescriptive, d’exposer des opérations CRUD pour le contenu du site, et il est intégré aux systèmes Entity API, Field API, de cache, d’authentification et d’autorisation de Drupal.

Cette phrase contient la partie qui devrait intéresser les dirigeants : module du cœur.

Le cœur compte. Le cœur signifie généralement moins de surprises côté fournisseurs, une planification de maintenance plus simple, une posture de sécurité plus claire et moins de risque du type « nous avons besoin du seul prestataire qui comprend la couche d’API personnalisée ». La documentation JSON:API de Drupal indique que le module expose des APIs autour des types d’entités et des bundles, prend en charge le filtrage, les includes, la pagination, le tri, les révisions, les traductions, GET, POST, PATCH, DELETE, l’upload de fichiers et la personnalisation des ressources via des événements.

Un exemple pratique : imaginez une entreprise média avec des articles, des auteurs, des sujets, des teasers de pages d’atterrissage et des images. L’équipe frontend a besoin de pages d’articles dans Next.js. L’application mobile a besoin du même corps d’article, de l’image hero, du nom de l’auteur et des sujets associés. JSON:API peut exposer ces entités Drupal sans obliger l’équipe backend à inventer un langage d’API à partir de zéro. Les ressources liées peuvent être intégrées via des includes, et les collections peuvent être filtrées ou paginées.

Le payload est-il élégant ? Parfois. Parfois, on dirait qu’un comité l’a conçu après un long déjeuner.

Mais c’est aussi le point. JSON:API est une spécification, pas le goût personnel d’un développeur. Le site officiel de JSON:API le décrit comme une spécification pour construire des APIs en JSON, avec des conventions partagées qui réduisent les débats sur la forme des réponses et aident les équipes à utiliser des outils généraux. Son type média est application/vnd.api+json, et la version 1.1 a été finalisée le 30 septembre 2022.

Il y a ici un bénéfice de management caché. Un format de réponse standardisé signifie que l’onboarding dépend moins du savoir tribal. Un nouveau développeur frontend pourra toujours maudire la structure imbriquée data, attributes et relationships. Très bien. Au moins, il maudit quelque chose de documenté.

Le piège que personne ne veut mentionner

JSON:API expose assez directement le modèle de contenu de Drupal. Cela peut être une force, surtout lorsque Drupal est la source éditoriale de vérité. Cela peut aussi laisser transparaître trop de la structure interne de Drupal dans le frontend.

Si votre modèle de contenu est propre, JSON:API paraît efficace. Si votre modèle de contenu est un musée de vieux compromis, JSON:API rend le désordre visible.

J’ai vu des types de contenu “Article” avec des champs comme field_new_body_2021, field_mobile_summary, field_legacy_related et field_do_not_use. JSON:API ne transforme pas magiquement cela en une API produit élégante. Il expose le modèle que vous avez réellement. Un peu cruel, peut-être. Utile, pourtant.

La documentation de Drupal établit également une limite claire : JSON:API gère le CRUD orienté entités, mais les règles métier comme la connexion, la réinitialisation du mot de passe et la création de compte ne relèvent pas de JSON:API. Si votre application a besoin d’actions métier comme « approuver un fournisseur », « calculer un devis de renouvellement » ou « soumettre une réclamation », ne les forcez pas dans des endpoints d’entités de contenu simplement parce que le module est pratique.

Cette voie devient vite très laide.

GraphQL semble élégant parce qu’il déplace la douleur

GraphQL est séduisant. Le frontend demande exactement les champs qu’il veut. La réponse a la même forme que la requête. Il possède un schéma typé. Il semble conçu pour les frontends basés sur des composants parce que, franchement, il l’a été. Le site officiel de GraphQL décrit GraphQL comme un langage de requête open source et un runtime côté serveur pour les APIs avec un schéma fortement typé, et montre le client demandant des champs sélectionnés au lieu de recevoir une réponse serveur fixe.

Pour les équipes frontend, c’est une vraie amélioration.

Prenez une page d’accueil composée de composants : hero, articles à la une, événements, emplacements sponsors, navigation, alertes régionales. Avec REST, le frontend peut appeler plusieurs endpoints. Avec JSON:API, il peut demander une collection et inclure des ressources liées, mais la structure suit toujours les relations entre entités. Avec GraphQL, la requête peut se rapprocher davantage de l’écran. C’est important lorsque les équipes livrent rapidement des surfaces produit.

Le module GraphQL de Drupal permet aux développeurs de concevoir et d’exposer un schéma GraphQL pour Drupal 10 et 11. Il est construit autour de webonyx/graphql-php, prend en charge la spécification officielle GraphQL, inclut GraphiQL à l’adresse /graphql/explorer, et fournit aux développeurs des plugins de producteurs de données ainsi que du code personnalisé pour le travail sur le schéma.

Lisez attentivement la formulation : « concevoir et exposer ».

Le module GraphQL actuel de Drupal n’est pas un miroir magique qui reflète simplement chaque champ Drupal dans une API bien ordonnée. Drupal.org indique que l’ancienne version 3.x générait automatiquement un schéma à partir des entités Drupal et exposait les détails de Drupal via l’API, tandis que la version 4.x laisse la conception du schéma au développeur afin que les détails internes de Drupal puissent être masqués. La même page indique que la version 4.x exige du développeur qu’il mette en place et mappe le schéma.

Ce n’est pas une note de bas de page. C’est la facture.

GraphQL peut vous donner un contrat propre entre le produit et le stockage du contenu. Mais quelqu’un doit concevoir ce contrat. Quelqu’un doit le maintenir lorsque les éditeurs ajoutent des champs, lorsque le design system change, lorsque la personnalisation arrive, lorsque le juridique demande une logique de consentement régional, lorsque l’équipe mobile a besoin de synchronisation hors ligne.

En réalité, c’est encore trop poli. Quelqu’un doit en être propriétaire. La propriété est la ligne budgétaire manquante dans beaucoup de propositions GraphQL.

Quand GraphQL vaut son coût

GraphQL a du sens lorsque l’API est un produit à part entière.

Une grande université avec des dizaines de microsites, une application mobile étudiante, de l’affichage numérique, des profils de professeurs, des catalogues de cours et un design system peut bénéficier d’une couche GraphQL. Les consommateurs sont variés. Le graphe de contenu est profond. Les équipes frontend ont besoin d’un accès sélectif. L’organisation peut vouloir un contrat d’API qui masque les excentricités des bundles Drupal.

GraphQL convient également lorsque Drupal n’est qu’une source parmi plusieurs. Peut-être que le contenu vient de Drupal, les prix d’un ERP, la disponibilité d’un moteur de réservation et les droits utilisateur d’un CRM. GraphQL peut présenter un schéma cohérent aux clients pendant que les resolvers récupèrent les données depuis différents systèmes. Le modèle GraphQL a été construit autour d’un schéma fortement typé et d’une forme de réponse spécifiée par le client, ce qui explique précisément pourquoi il fonctionne bien dans ce type de couche de composition.

Mais pour un site marketing ordinaire avec un frontend headless ? Je serais sceptique. Même légèrement agacé.

Si le vrai besoin est « React doit lire des articles depuis Drupal », GraphQL peut être une fête costumée. Vous dépenserez de l’argent d’architecture pour éviter d’apprendre les includes et les filtres JSON:API. Pire, vous pourriez créer une couche d’API sur mesure que seuls deux développeurs comprennent.

La page du projet GraphQL de Drupal indique que les versions stables sont couvertes par la politique d’avis de sécurité de Drupal et liste les versions récentes pour Drupal 10 et 11, notamment 8.x-4.14 publiée le 29 avril 2026 et une bêta 5.0.0 pour Drupal 10.4 et 11. C’est sain. Cela ne supprime pas le travail de conception.

Un module contribué peut être mature et rester le mauvais choix par défaut.

RESTful Web Services : ancien, utile et généralement surutilisé

REST est devenu l’un de ces mots qui signifient ce dont l’orateur a besoin. Parfois, cela signifie un HTTP propre orienté ressources. Parfois, cela signifie « nous retournons du JSON depuis un controller ». Parfois, cela signifie « le fournisseur nous a donné un endpoint et un PDF ».

La thèse de Roy Fielding a introduit REST comme un style architectural pour des systèmes hypermédia distribués, avec des contraintes telles que la séparation client-serveur, la communication sans état, le cache, une interface uniforme, des systèmes en couches et le code à la demande optionnel. Cette idée originale est plus stricte que beaucoup de ce qui est appelé REST dans les plans de projet.

Le module RESTful Web Services de Drupal est utile parce qu’il peut exposer des ressources avec des méthodes spécifiques, des formats de sérialisation et une authentification. Le matériel d’étude Drupal décrit des ressources REST pour les entités, la prise en charge de méthodes telles que GET, POST, PATCH et DELETE, la sérialisation JSON ou XML, et l’authentification via Basic Auth, cookies ou d’autres modules comme OAuth. Il note également que les méthodes non sûres exigent un en-tête de requête X-CSRF-Token.

Cela rend REST adapté aux travaux d’intégration étroits.

Un prestataire de paiement publie le statut d’une transaction vers Drupal. Un système d’entrepôt récupère une liste de manuels produit mis à jour. Un portail partenaire a besoin d’un endpoint soigneusement façonné pour les assets approuvés. Une ancienne application mobile attend déjà /api/v1/articles/{id} et ne peut pas être réécrite ce trimestre.

REST vous donne du contrôle. Il vous donne aussi le syndrome de la page blanche.

Contrairement à JSON:API, où les conventions sont déjà choisies, un endpoint REST personnalisé exige des décisions : forme de l’URL, format de réponse, format d’erreur, style de pagination, syntaxe de filtrage, versioning, authentification, en-têtes de cache, documentation, politique de dépréciation. OpenAPI peut aider à documenter cette surface, et la spécification OpenAPI est une manière standard et indépendante du langage de décrire des APIs HTTP afin que les humains et les ordinateurs puissent les comprendre sans lire le code source.

Mais vous devez quand même faire ces choix.

Et ces choix restent. Un endpoint bâclé conçu en deuxième semaine peut hanter le produit pendant des années parce qu’une version d’application encore en circulation en dépend toujours.

La décision n’est pas « quelle API est la meilleure ? »

Ce cadrage est paresseux. Désolé, mais il l’est.

La meilleure question est : quel type de couplage votre organisation peut-elle se permettre ?

JSON:API couple les consommateurs au modèle d’entités de Drupal. C’est souvent acceptable lorsque Drupal est le système de contenu principal et que le frontend est une couche de présentation de remplacement. La récompense est la rapidité et moins d’invention côté backend.

GraphQL couple les consommateurs à un schéma conçu par votre équipe. Bien fait, ce schéma masque Drupal et exprime le domaine produit. Mal fait, il devient un second modèle de CMS maintenu dans le code.

REST couple les consommateurs à des endpoints personnalisés. C’est excellent pour des intégrations spécifiques et dangereux pour une diffusion large de contenu, car chaque endpoint devient un produit miniature avec sa propre traîne de maintenance.

Voici la version que je mettrais devant un comité de pilotage exécutif.

Les tableaux sont un peu stériles, mais celui-ci économise des réunions.

Ce que les chefs de projet devraient surveiller

Le choix de l’API modifie le plan projet plus que les gens ne l’admettent.

Avec JSON:API, le chemin critique est la modélisation du contenu. Si le modèle de contenu est bien pensé, le travail d’API peut avancer rapidement. Si le modèle de contenu est chaotique, le développement frontend ralentit parce que chaque requête expose un autre compromis éditorial. Mettez une attention senior sur le nommage des champs, les patterns de paragraphes réutilisables, les relations médias, la taxonomie et les permissions avant que l’équipe frontend commence à câbler les pages.

Avec GraphQL, le chemin critique est la propriété du schéma. Qui conçoit le schéma ? Qui révise les breaking changes ? Qui écrit les resolvers ? Qui gère les problèmes de performance comme les requêtes imbriquées qui déclenchent trop de chargements backend ? Le module Drupal GraphQL fournit des outils et des points d’extension, notamment des plugins de producteurs de données et GraphiQL, mais il ne supprime pas la nécessité d’une discipline d’ingénierie backend.

Avec REST, le chemin critique est la discipline contractuelle. Chaque endpoint a besoin de documentation, de tests, de règles d’authentification, d’une sémantique d’erreurs et d’une histoire de versioning. REST paraît bon marché lorsque le premier endpoint est construit. Le cinquième endpoint dit la vérité.

Encore une chose. L’authentification est souvent sous-estimée. Drupal JSON:API est lié aux systèmes d’authentification et d’autorisation de Drupal, et REST peut utiliser des fournisseurs d’authentification comme Basic Auth et les cookies, OAuth étant souvent ajouté via des modules contribués. La documentation Lupus Decoupled Drupal indique Simple OAuth comme moyen d’authentifier les requêtes API par token dans des configurations découplées.

Ne laissez pas cela pour le sprint avant le lancement. Ce sprint est déjà maudit.

Performance : l’argument que tout le monde simplifie

Les fans de GraphQL disent qu’il évite l’over-fetching. Vrai. Les fans de JSON:API disent que les includes réduisent les allers-retours. Vrai aussi. Les fans de REST disent que le cache HTTP est simple. Encore vrai.

Maintenant, la partie désagréable : les trois peuvent être rapides, et les trois peuvent être lents.

GraphQL peut réduire la taille du payload, mais les requêtes imbriquées complexes peuvent punir le backend si les resolvers sont négligents. JSON:API peut utiliser le cache de réponse de Drupal et les includes, mais les payloads peuvent être verbeux. REST peut se mapper proprement au cache HTTP, mais les endpoints personnalisés oublient souvent la cacheability jusqu’au début des tests de performance. Les contraintes REST de Fielding incluent le cache parce qu’il peut réduire le trafic réseau et la latence, mais les données obsolètes et l’invalidation du cache restent de vrais compromis. La documentation JSON:API de Drupal lie explicitement le module au cache de réponse Drupal, tandis que le module GraphQL est classé sur Drupal.org dans Découplé, Outils de développement et Performance.

Donc non, GraphQL n’est pas automatiquement « l’option performance ».

Le premier gain de performance est généralement une meilleure modélisation du contenu. Le deuxième est une stratégie de cache. Le troisième est d’éviter les comportements clients absurdes, comme appeler le même endpoint douze fois parce que personne n’a écrit de couche d’accès aux données.

Glamour ? Non. Efficace ? Oui.

Un cadre de sélection direct

Si je conseillais un fondateur ou un CTO, je commencerais par cette séquence.

Premièrement, utilisez les pages rendues normales de Drupal sauf si vous avez une raison de découpler. Le découplage ajoute de la complexité d’hébergement, de preview, de routing, de cache, de déploiement, d’authentification et de débogage. La propre documentation de Drupal sur le découplage distingue Drupal standard de Drupal découplé en notant que le layout passe au frontend et que le backend expose le contenu via des APIs. Ce changement n’est pas gratuit.

Deuxièmement, si vous découplez principalement pour un frontend moderne, commencez avec JSON:API. Construisez une vraie page, pas une démo. Incluez les médias, les menus ou la navigation, le contenu lié, les besoins de preview, l’authentification si nécessaire et le comportement de cache. Vous apprendrez davantage d’une page imparfaite que de six diagrammes d’architecture.

Troisièmement, passez à GraphQL uniquement lorsque l’expérience consommateur justifie le travail sur le schéma. Les bonnes raisons incluent plusieurs consommateurs frontend, le besoin de masquer les détails internes de Drupal, des graphes de contenu complexes ou l’agrégation entre systèmes. Les mauvaises raisons incluent « notre développeur frontend aime Apollo » et « le deck investisseur dit GraphQL ».

Quatrièmement, utilisez REST pour les intégrations qui ont besoin de limites strictes. Un endpoint personnalisé pour un export partenaire peut être propre. Une plateforme de contenu entière composée d’endpoints faits à la main peut devenir un tiroir rempli de clés sans étiquette.

Et nettoyez le modèle Drupal. S’il vous plaît. Aucune couche d’API ne peut sauver complètement un modèle de contenu dont personne n’est propriétaire.

La politique du « future-proof »

Les dirigeants aiment l’expression « future-proof ». Je comprends pourquoi. Personne ne veut approuver une reconstruction backend et entendre, dix-huit mois plus tard, que l’API choisie a enfermé l’entreprise dans une impasse.

Mais la préparation à l’avenir consiste généralement moins à choisir l’API la plus sophistiquée qu’à décider où le changement est autorisé à se produire.

JSON:API dit : « Le modèle de Drupal est le contrat. » C’est honnête et rapide.

GraphQL dit : « Notre schéma produit est le contrat. » C’est puissant et coûteux.

REST dit : « Cet endpoint est le contrat. » C’est précis et facile à multiplier jusqu’à devenir un problème de maintenance.

Il n’y a pas de gagnant universel. Il n’y a que l’adéquation.

Mon biais est simple : commencez par la chose la moins personnalisée capable de soutenir le produit. Dans Drupal, cela signifie généralement JSON:API. Ajoutez GraphQL lorsque vous pouvez nommer le propriétaire et le budget. Ajoutez REST lorsque l’intégration est suffisamment spécifique pour mériter sa propre porte.

Le pire choix est celui fait par effet de mode, parce que la mode ne se présente jamais pour la maintenance.

Vous recherchez la meilleure entreprise de développement Drupal du marché ? Vous venez de la trouver.

Nous sommes la meilleure agence digitale spécialisée Drupal, conçue pour livrer des plateformes rapides, sécurisées et scalables, sans compromis. Des nouveaux projets et refontes aux migrations et au support long terme, nos experts Drupal livrent des résultats de niveau entreprise avec l’attention d’une agence boutique.

Réservez un appel dès aujourd’hui et transformons votre roadmap Drupal en une réalité hautement performante.