API GraphQL : conception de schéma, résolveurs et mutations efficaces

Développement Renard orange à lunettes devant un ordinateur portable, avec une base de données et un tableau présentant un schéma de données ramifié et des flèches de cycle.

Table des matières :

  1. API GraphQL : le schéma est un contrat, pas un moodboard
  2. Résolveurs GraphQL : là où la performance se gagne (ou se perd) en silence
  3. Mutations efficaces : moins de magie, plus d’atomicité
  4. Sécurité GraphQL : l’open bar, c’est au bar. Pas sur Internet.
  5. Mettre une API GraphQL en production sans finir en post-mortem

API GraphQL : le schéma est un contrat, pas un moodboard

Une API GraphQL n’est pas “une API REST mais en plus swag”. C’est un contrat typé exposé à des clients qui vont littéralement le parser, générer du code dessus, et le casser dès que vous faites une “petite modif rapide”. La phrase officielle de GraphQL résume bien l’objet :

« GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data » (GraphQL Foundation, site officiel de GraphQL)

Traduction opérationnelle : vous vendez un langage + un runtime, donc votre schéma devient la pièce maîtresse. C’est aussi pour ça que GraphQL est très à l’aise dans des équipes multi-clients (web, app, POS, back-office) — et très punitif quand le schéma est bricolé.

Techniquement, le schéma (SDL) définit des types, des relations, des inputs, des enums et la nullability. Et la nullability, c’est l’endroit où beaucoup d’équipes révèlent leur talent caché pour l’auto-sabotage. Un champ nullable signifie que sa valeur peut être null ; le client doit donc gérer ce cas. C’est acceptable… si c’est vrai. Un champ String! signifie que sa valeur ne peut pas être null dans une réponse valide. Si un résolveur renvoie null ou déclenche une erreur pour ce champ, GraphQL signale une erreur et la valeur null se propage jusqu’au champ nullable le plus proche. Bref : décider de ! est un choix produit et SRE, pas une préférence esthétique.

Deux heuristiques simples (qui évitent beaucoup de bugs côté front) :

  • Non-null par défaut sur les invariants métier : un Product.id, un sku, un title… si “parfois c’est null”, ce n’est pas un champ, c’est un incident ou une règle à clarifier.
  • Nullable là où une valeur nulle a du sens : discount, compareAtPrice, deliveryDateEstimate, companyName… et documentez pourquoi la valeur peut être nulle (stock inconnu, calcul asynchrone, source externe non disponible, etc.).

Prenons un exemple e-commerce (parce que c’est là que les API GraphQL souffrent sous la charge) : ne modélisez pas un prix en Float. Un prix est un Money (montant + devise), sinon vous allez découvrir les joies du rounding et du multi-currency en production (et en Europe, “juste l’euro” devient vite “euro + GBP + CHF” dès que vous ouvrez le catalogue à l’international). Même combat pour les dates : String “ça passe”… jusqu’au premier fuseau horaire, puis c’est un incident. Utilisez des scalars custom (DateTime, URL, Email), et documentez leur format.

scalar DateTime

type Product {
  id: ID!
  sku: String!
  title: String!
  price: Money!
  updatedAt: DateTime!
}

type Money {
  amount: String! # decimal en string (ou BigDecimal côté serveur)
  currency: CurrencyCode!
}

enum CurrencyCode { EUR USD GBP }

Sur Money.amount : le commentaire “decimal en string” n’est pas une coquetterie. Beaucoup de stacks (JS/TS notamment) n’ont pas de décimal natif fiable ; forcer un Float côté contrat encourage des conversions hasardeuses. Si vous préférez, vous pouvez aussi exposer un Int en “minor units” (cents) — mais choisissez et tenez la ligne.

Au passage, si votre schéma ressemble à un dump de tables SQL (types qui s’appellent ProductEntity, champs created_at, etc.), félicitations : vous venez d’inventer une API couplée à votre ORM. Un bon design GraphQL modélise des capacités métier, pas des colonnes. Concrètement, ça se voit sur :

  • les noms (availableForSale plutôt que is_available),
  • les agrégats (Cart, Checkout, InventoryStatus) plutôt que des “lignes”,
  • les relations orientées usages (ex. Product.media avec filtrage/tri) plutôt que “toutes les jointures possibles”.

C’est exactement ce qu’on attend dans un contexte headless où plusieurs frontaux (web, app, POS) consomment le même contrat — cf. l’article interne sur le sujet : Headless e-commerce : avantages, limites et critères de décision.

Un point souvent oublié : la pagination fait partie du contrat. Si vous exposez products: [Product!]! sans arguments, vous préparez une future requête “export catalogue” qui va exploser votre DB. Le minimum viable côté schéma, c’est d’offrir une pagination (offset ou cursor) et de borner first/limit. Dans des catalogues volumineux (retail, B2B), la cursor pagination est souvent plus stable, en particulier quand les résultats sont ordonnés de façon cohérente :

  • performances plus constantes,
  • moins de doublons/sauts quand les données changent,
  • plus robuste pour des frontaux qui rafraîchissent souvent.

Dernier point de gouvernance : la “version v2” du schéma est rarement nécessaire si vous exploitez correctement @deprecated. GraphQL assume l’évolution incrémentale : vous ajoutez, vous dépréciez, puis vous supprimez quand plus personne n’appelle. Oui, ça implique de mesurer l’usage des champs. Non, “on pense que personne ne l’utilise” n’est pas une métrique. En pratique, il vous faut au moins :

  • un log des opérations (nom d’opération, client, version d’app),
  • une fenêtre de dépréciation annoncée,
  • un garde-fou en CI sur les breaking changes (suppression/renommage/changement de type).

Résolveurs GraphQL : là où la performance se gagne (ou se perd) en silence

Un résolveur GraphQL est la fonction exécutée pour produire la valeur d’un champ. En pratique, c’est la couche d’orchestration entre votre schéma et vos sources de données : DB, services internes, cache, SaaS, etc. Et c’est aussi l’endroit où naît le fameux problème N+1 : une requête pour la liste, puis N requêtes pour chaque item. Le genre de bug “invisible” en local, et “catastrophique” quand vous avez 2 000 produits dans un panier B2B.

Mini-scénario (très réaliste) : votre page “commande” affiche 50 lignes + pour chaque ligne le produit, la TVA, la disponibilité stock (service externe) et le vendeur (table users). Sans batching, vous vous retrouvez avec :

  • 1 requête pour la commande,
  • 50 requêtes produits,
  • 50 requêtes vendeurs,
  • 50 appels stock…

Même si chaque appel ne prend “que” 10 ms, le volume d’appels peut faire grimper fortement la latence, notamment si certains appels s’enchaînent ou sont limités en concurrence. Le p95 ne se résume pas à une moyenne.

La solution de base : batching + caching par requête. Le pattern le plus répandu est DataLoader (DataLoader sur GitHub). Vous collectez toutes les clés demandées pendant l’exécution, vous faites une requête groupée (WHERE id IN (...)), puis vous mappez le résultat. Important : le cache DataLoader est scopé à la requête (request-scoped), pas global, sinon vous allez réinventer des bugs de cohérence. Et si vous avez besoin d’un cache multi-requêtes, utilisez un cache applicatif (Redis/Memcached) avec invalidation claire.

// pseudo-code TypeScript
const userLoader = new DataLoader(async (ids: readonly string[]) => {
  const rows = await db.user.findMany({ where: { id: { in: [...ids] } } });
  const byId = new Map(rows.map(r => [r.id, r]));
  return ids.map(id => byId.get(id) ?? null);
});

const resolvers = {
  Order: {
    customer: (order, _, ctx) => ctx.loaders.user.load(order.customerId),
  }
}

Deux détails qui font la différence en prod :

  • Respectez l’ordre des ids : DataLoader s’attend à recevoir les résultats dans le même ordre que les clés. D’où le ids.map(...) final (et pas “je retourne rows”).
  • Décidez votre politique “not found” : null ? Erreur ? Dans un schéma bien pensé, “pas trouvé” est souvent null sur un champ nullable, et erreur métier sur une mutation (cf. section suivante).

Ensuite, optimisez le “fetch” en utilisant l’info disponible côté GraphQL : le selection set. Si le client ne demande que id et title, inutile de charger 20 colonnes et 3 jointures. Selon vos technos, vous pouvez : (1) projeter explicitement via l’ORM, (2) utiliser un query planner, (3) précharger via des JOIN ou des INCLUDE. Objectif : réduire le nombre de round-trips DB, et surtout la variance de latence (p95/p99). Une API GraphQL “rapide en moyenne” mais instable au p99 est une API qui déclenche des timeouts au mauvais moment (campagne, soldes, import massif… vous voyez le tableau).

Une checklist pragmatique côté résolveurs (utile avant un pic type Black Friday / soldes en France) :

  • Est-ce que ce champ déclenche un appel réseau ? Si oui, timeout + retry maîtrisé + circuit breaker (au minimum, un fallback).
  • Est-ce que ce champ peut être demandé en liste ? Si oui, batching obligatoire.
  • Est-ce que ce champ dépend du contexte utilisateur (prix B2B, TVA, stock par entrepôt) ? Si oui, attention aux caches “trop globaux”.
  • Est-ce que ce champ varie rarement ? Si oui, cache applicatif avec TTL (et invalidation si nécessaire).

Pour la couche cache, GraphQL n’est pas “anti-cache”, il est “anti-cache naïf”. Le caching HTTP type CDN/Varnish est compliqué parce que la plupart des requêtes sont en POST avec un body unique. Mais vous pouvez (et devriez) combiner : persisted queries (requêtes pré-enregistrées identifiées par hash), GET pour les opérations de query sûres, et cache applicatif sur les agrégats. Si vous cherchez des patterns cache, ça vaut le détour de lire : Varnish Cache : optimiser le cache HTTP et réduire la charge serveur et, pour le cache objet côté applicatif, même si l’article parle WordPress, les principes sont transposables : Redis : guide d’implémentation du cache objet WordPress performant.

Côté observabilité, ne jouez pas à “deviner” quel résolveur de champ a explosé. Tracez. Une instrumentation OpenTelemetry sur les résolveurs (span par opération, puis par data source critique) transforme une chasse au bug en diagnostic. Pour l’outillage et la terminologie : OpenTelemetry : unifier métriques, traces et logs pour l’observabilité.

Un ajout concret qui aide beaucoup : journaliser (ou métrifier) un coût par opération. Pas besoin de réinventer une thèse : vous pouvez commencer avec 3 signaux simples par requête GraphQL :

  • nombre total de champs résolus,
  • profondeur maximale,
  • nombre d’appels par data source (DB, service stock, service prix).

Ça vous donne une base objective pour dire “cette opération coûte 10x plus depuis hier” — et donc pour agir avant que le support ne vous appelle.

Mutations efficaces : moins de magie, plus d’atomicité

Une mutation GraphQL est une opération qui modifie l’état. Contrairement aux champs de query, les champs de mutation de premier niveau sont exécutés en série (ce comportement est défini dans la spécification GraphQL, section “Execution”, spécification GraphQL). Ça ne rend pas votre backend “transactionnel par défaut” (désolé), mais ça donne un ordre déterministe côté runtime.

Concevoir une mutation “efficace” signifie surtout : input structuré, validation précoce, erreurs utiles, et résultat exploitable. Le pattern “Input + Payload” reste une valeur sûre, notamment parce qu’il facilite l’évolution (ajout de champs optionnels) et la génération de clients typés.

input AddToCartInput {
  cartId: ID!
  sku: String!
  quantity: Int!
}

type AddToCartPayload {
  cart: Cart!
  userErrors: [UserError!]!
}

type UserError {
  code: String!
  message: String!
  path: [String!]!
}

type Mutation {
  addToCart(input: AddToCartInput!): AddToCartPayload!
}

Deux améliorations fréquentes dans des contextes e-commerce / retail (et qui évitent des tickets côté front) :

  • Renvoyer aussi un “résumé” prêt à afficher : totaux TTC/HT, frais de livraison estimés, nombre d’articles. Ça évite une requête supplémentaire juste pour mettre à jour un mini-panier.
  • Prévoir un champ d’extension d’erreurs (quitte à rester simple) : code pour automatiser des comportements (ex. OUT_OF_STOCK, MIN_QUANTITY_NOT_REACHED), path pour pointer le champ, et un message pour l’humain.

Au niveau métier, pensez idempotence et concurrence. “Ajouter au panier” peut être idempotent si vous l’implémentez comme “set quantity” ou si vous utilisez une clé de déduplication (par ex. clientRequestId). Pour des opérations critiques (paiement, création de commande), vous voulez une transaction DB (ou saga) + un mécanisme de verrouillage optimiste (champ version, updatedAt, etc.) pour éviter les effets “double clic” — parce que oui, vos utilisateurs double-cliquent. Les clients mobiles le font même sans le vouloir (réseau instable, écran figé, retry automatique).

Et non, “mettre tout dans une mutation monolithique qui fait 12 side-effects” n’est pas une stratégie, c’est une dette. Si une mutation déclenche un traitement long (fraude, génération PDF, sync ERP), rendez-la asynchrone : retournez un jobId, publiez un event, et laissez un worker faire le boulot. Les frontaux aiment aussi la vérité : “c’est en cours” plutôt que “ça timeout mais peut-être que c’est passé”.

Petit repère de conception (utile quand plusieurs équipes touchent aux mutations) :

  • Mutation synchrone : création/édition simple, effets bornés, transaction DB courte, latence prévisible.
  • Mutation asynchrone : dépendances externes, traitements > 1–2 secondes, enchaînements multiples, risque de retry.

Dernier point qui change la vie : faites remonter des objets frais dans le payload (ex. cart complet) pour éviter au client une requête supplémentaire. Oui, ça augmente la taille de la réponse ; non, ce n’est pas un crime si vous gardez un œil sur la latence et le coût DB. Les équipes qui optimisent “à coup de petites réponses” finissent souvent avec… plus d’appels réseau.

Sécurité GraphQL : l’open bar, c’est au bar. Pas sur Internet.

Une API GraphQL n’est pas intrinsèquement moins sécurisée que REST. Elle est juste beaucoup plus expressive, donc elle offre plus de surface d’abus si vous ne mettez pas de garde-fous. L’authentification est nécessaire, mais l’autorisation — notamment le contrôle de l’accès aux objets — est souvent un enjeu central. La sécurité GraphQL, ce n’est pas seulement une question de JWT.

Concrètement : faites de l’autorisation au niveau des champs ou au niveau des résolveurs critiques (et pas seulement “au niveau de la route /graphql”). Séparez les scopes, imposez des checks “owner” systématiques, et journalisez les refus. Pour une approche structurée côté API (authn + authz + logique métier), vous pouvez recouper avec : Sécurité des API : authentification, autorisations et logique métier.

Pour situer le risque : OWASP classe l’autorisation objet cassée parmi les principaux problèmes de sécurité des API (projet OWASP API Security, projet OWASP API Security). Et GraphQL ne “crée” pas BOLA, il peut juste la rendre plus simple à exploiter si vous exposez des IDs et des relations sans contrôles fins.

Ensuite, gérez l’abus “technique” : profondeur, complexité, volumétrie. Un attaquant n’a pas besoin de faire 10 000 requêtes si une seule requête GraphQL peut demander 50 000 nœuds. Mettez des limites : max depth, max complexity, timeouts, rate limiting, et idéalement une allowlist d’opérations via persisted queries (ce qui aide aussi la perf). Oui, ça râle en interne au début (“mais c’est moins flexible”), puis ça évite l’incident du vendredi 18h.

Un bon compromis côté produit (surtout quand vous avez des partenaires, marketplaces, ou apps mobiles en production) :

  • en prod : allowlist + persisted queries pour les clients publics,
  • en staging : plus permissif pour itérer,
  • en interne : un “playground” avec des droits stricts et un monitoring renforcé.

Sur l’introspection : la désactiver en prod est un réflexe courant, mais ce n’est pas une solution miracle. Si vos contrôles d’accès sont bons, l’introspection révèle surtout la forme du schéma, pas les données. En revanche, elle aide un attaquant à automatiser l’exploration. Une approche pragmatique : introspection autorisée uniquement pour des rôles internes/outil d’admin, et blocage/filtrage WAF sur des patterns connus. Pour l’outillage côté règles/WAF, vous pouvez regarder : Cloudflare Custom Rules : créer et gérer des règles WAF personnalisées et, pour une philosophie “ne jamais faire confiance”, le cadre : Zero-trust : déployer une architecture NIST SP 800-207 en entreprise.

Enfin, ne négligez pas la supply chain : schéma généré, dépendances GraphQL server, gateway, plugins… Tout ça vit dans votre pipeline. Si votre CI/CD laisse passer une lib vulnérable ou un secret en clair, GraphQL n’y est pour rien, mais c’est vous qui prenez. À lire : Sécurité CI/CD : protéger dépôts, runners, secrets et artefacts.

Mettre une API GraphQL en production sans finir en post-mortem

La prod GraphQL se joue sur trois axes : réseau, scalabilité, gouvernance de schéma. Côté réseau, vous voulez du TLS moderne, de la compression maîtrisée, et une infra qui ne transforme pas chaque requête en loterie. HTTP/2 et HTTP/3 ne rendent pas GraphQL magique, mais ils peuvent réduire le coût des connexions et améliorer la multiplexation. Si vous devez revoir votre stack proxy/TLS : NGINX : maîtriser HTTP/2, HTTP/3 QUIC et TLS 1.3 et HAProxy : déployer un reverse proxy et load balancer sécurisé.

Côté scalabilité, arrêtez de piloter “à l’instinct”. Définissez des SLO (latence p95/p99 par opération, taux d’erreur, saturation DB), instrumentez vos résolveurs, et alertez sur les bonnes métriques. GraphQL a une particularité : une régression de perf peut être liée à un champ très spécifique introduit la veille. Les dashboards globaux “CPU/RAM” ne suffisent pas.

Un exemple de SLO simple mais utile (à adapter) :

  • Opérations critiques checkout/panier : p95 < 300 ms, p99 < 800 ms
  • Catalogue : p95 < 500 ms, p99 < 1 200 ms
  • Taux d’erreur (erreurs serveur et erreurs GraphQL inattendues) : < 0,5%

Même si vous ne tenez pas ces chiffres au début, les écrire oblige à définir ce que “rapide” signifie pour votre contexte (et à arrêter de confondre “ça va sur ma machine” avec “ça tient un samedi de soldes”).

Si vous êtes déjà dans l’écosystème Prometheus, vous avez de quoi faire : Prometheus : architecture monitoring, PromQL, Alertmanager et Grafana et, pour la mise en prod Kubernetes, kube-prometheus-stack : déploiement Helm et Prometheus Operator en production.

La gouvernance de schéma, c’est le sujet que tout le monde repousse (“on verra plus tard”) jusqu’au moment où trois équipes déploient trois versions incompatibles. Mettez en place : (1) des checks de breaking changes en CI (diff de schéma), (2) un cycle de dépréciation avec date cible, (3) un registry (même simple) pour tracer qui consomme quoi. Et, si vous partez sur de la fédération (Apollo Federation / GraphQL Mesh / gateway maison), imposez des conventions strictes sur la propriété des types et la résolution des références, sinon votre graphe devient un champ de mines.

Un garde-fou très concret (et très rentable) : avant de merger un changement de schéma, exigez au moins une réponse à ces questions dans la PR :

  • Ce changement est-il breaking (type, nullability, renommage) ?
  • Quel client est impacté (web, app, partenaire) ?
  • A-t-on un plan de dépréciation (date + mesure d’usage) ?
  • Quels résolveurs ou sources de données sont touchés (risque perf) ?

Dernier rappel un peu “transactionnel” (promis, pas trop) : une API GraphQL propre est souvent le reflet d’une architecture propre. Quand le schéma est bancal, les résolveurs font des acrobaties et les mutations font des miracles, c’est généralement le signe qu’il faut une vraie roadmap technique et une revue sérieuse. Pour ça, il existe des options qui évitent de réinventer la roue en sprint 12 : Feuille de route technique, Direction technique externalisée et, si vous voulez challenger vos résolveurs, contrôles d’accès et patterns de mutation avant l’attaque (ou avant le pic de trafic), Revue et sécurisation du code.

Si vous devez retenir une règle simple : en GraphQL, tout ce que vous laissez “flexible” côté serveur finit par devenir “exploitable” côté client… ou côté attaquant. À vous de choisir qui bénéficie de cette flexibilité.


Kévin DECQ-CAILLET, Directeur associé

Co-fondateur du studio de développement Les Vikings, mon cœur est voué aux paradoxes. Amour de la technologie et de l'Histoire, passion pour la gestion, le potager et le béhourd - si vous ne connaissez pas, ça vaut le détour. Accessoirement, une expérience de plus de 15 ans dans le domaine du numérique. Ce qui implique que j'en sais assez pour constater que j'ai encore beaucoup à apprendre.

Résumé de la politique de confidentialité

Ce site utilise des cookies afin que nous puissions vous fournir la meilleure expérience utilisateur possible. Les informations sur les cookies sont stockées dans votre navigateur et remplissent des fonctions telles que vous reconnaître lorsque vous revenez sur notre site Web et aider notre équipe à comprendre les sections du site que vous trouvez les plus intéressantes et utiles.