🤔 GraphQL devrait-il être différent pour différents utilisateurs ?

GraphQL est une interface pour récupérer des données d'une source, la spec GraphQL définissant les exigences pour cette interface. Tant que ces exigences sont satisfaites, GraphQL ne se soucie pas de la façon dont c'est accompli. Le serveur GraphQL peut alors être implémenté en JavaScript en utilisant des promises, en utilisant une architecture concurrente basée sur Golang, mappé à un fichier Excel, ou autre, et tout cela peut constituer des implémentations valides de la spec GraphQL.

La façon dont le moteur du serveur est implémenté n'est pas importante pour l'exécution réussie d'une requête GraphQL, car l'interaction entre le client et le serveur est toujours la même : elle se déroule en soumettant une requête GraphQL en utilisant une syntaxe définie, et en obtenant une réponse correspondante au format JSON.

Maintenant, quand je dis que l'implémentation n'est pas importante, je le dis du point de vue de l'utilisateur de l'API, qui cherche simplement à obtenir des données du serveur. La façon dont les données retournées ont été produites ne présente aucun intérêt.

Mais la situation change pour le développeur côté serveur qui travaille sur l'API, pour qui les détails de l'implémentation sont en effet très importants. Si je code mon API GraphQL en PHP, je ferai de mon mieux pour que mon API soit résolue aussi efficacement que possible, et pour avoir une conception architecturale aussi élégante que possible, en utilisant les capacités offertes par PHP.

Nous avons donc un possible conflit d'intérêts entre la nécessité de protéger l'API et les capacités attendues par les développeurs travaillant sur l'API, qui ne veulent pas se voir retirer des fonctionnalités supportées par le langage sous-jacent (comme la possibilité d'exécuter du code récursif).

Ce conflit est devenu évident dans l'issue #929: Allow recursive references in fragments, qui soutient que GraphQL ne devrait pas interdire les récursions dans les fragments.

Lors d'une réunion passée du groupe de travail GraphQL, Roman, le développeur qui a soulevé l'issue, a exprimé pourquoi il est en désaccord avec la limitation imposée par la spec :

Je suis développeur côté serveur, et j'ai l'impression que la spec parle trop de l'exécution côté serveur, alors qu'elle devrait se concentrer sur ce que le client veut recevoir — pas sur comment

La règle interdisant les récursions dans les fragments a été justifiée sur la prémisse de maintenir l'API publique sécurisée. Après tout, GraphQL a été créé par Facebook pour fournir des données à son application publique, et les utilisateurs ne devraient pas être capables d'exploiter une faille dans la conception de l'API qui pourrait faire tomber le service.

Le créateur de GraphQL, Lee Byron, a exprimé trois préoccupations majeures :

récursion infinie ; les limitations ne seraient pas seulement une spécification — comment et quand devrait-elle s'arrêter

validation des données ; retourner la même valeur plusieurs fois, comment est-ce représenté dans les données. Idéalement, vous souhaitez détecter qu'elle est cyclique et arrêter immédiatement, mais certains serveurs ne peuvent pas détecter cela et peuvent boucler de nombreuses fois avant de détecter que quelque chose a mal tourné et de s'arrêter

quel est le coût de ne pas avoir cela ; est-ce que cela justifie ces problèmes ? Non ; il est toujours possible de spécifier le nombre de niveaux de profondeur dans votre requête — c'est effectivement la version désimbriquée de ce que nous ferions si nous gérions cela dans GraphQL

Venant de leurs propres perspectives, Roman et Lee ont tous les deux raison. Lee Byron s'inquiète de la sécurité de l'API GraphQL publique. Éviter les fragments récursifs est justifié pour s'assurer qu'aucun acteur malveillant ne puisse faire tomber le système en exécutant une boucle cyclique sans fin dans la requête, et même éliminer le risque d'un « self-DDoSing » d'équipe, ce qui pourrait se produire si une requête bloquant le système est publiée involontairement.

Roman, cependant, est préoccupé par les limitations à ses propres capacités pour créer une API GraphQL. Comme Roman peut être le seul consommateur de son API (c'est-à-dire une API privée qui n'est pas exposée aux utilisateurs), ou parce que son serveur peut avoir la capacité de détecter et d'arrêter les cycles récursifs, il estime que la limitation de GraphQL est préjudiciable et injustifiable.

Au cœur de la discussion, le problème n'est pas de savoir si les fragments récursifs devraient être autorisés ou non, mais quelque chose de plus fondamental : qui est la cible de GraphQL ? Si ce n'est pas un seul groupe, une seule spécification d'API pourrait-elle satisfaire les exigences de tous les différents acteurs ? Et si le conflit ne peut être évité, peut-il au moins être remédié d'une façon ou d'une autre ?

Explorons ces questions.

​

Qui est la cible de GraphQL ?

GraphQL est utilisé par différents types d'acteurs, parmi lesquels nous pouvons identifier :

1. Utilisateurs de l'API : Ceux qui consomment des données d'un endpoint GraphQL, pour quelque raison que ce soit. Par exemple, nous pouvons tous être des utilisateurs de l'API GraphQL publique de GitHub, pour récupérer des données concernant nos dépôts GitHub.

2. Développeurs côté client : Ceux qui créent des applications côté client alimentées par un endpoint GraphQL. Par exemple, les développeurs qui construisent des sites avec Gatsby s'appuient sur GraphQL pour récupérer le contenu du site.

3. Développeurs backend : Ceux qui créent les resolvers pour l'API GraphQL.

De plus, nous devons noter que l'API GraphQL peut être publique ou privée :

API publique : Comme tout le monde a accès à l'endpoint GraphQL, nous devons nous préoccuper des mesures de sécurité pour éviter les attaques d'acteurs malveillants.

API privée : Comme seuls les acteurs prévus se voient accorder l'accès à l'API, il n'y a pas de risques de sécurité inhérents, et le self-DDoSing peut être facilement évité avec de bonnes pratiques de codage.

​

Une seule spécification d'API satisfait-elle les exigences de tous les acteurs ?

L'issue soulevée par Roman peut être interprétée ainsi : « Si mon API GraphQL est privée, et que je sais exactement ce que je fais (ayant une certitude à 100 % que mon code fonctionnera comme prévu et qu'aucune exécution bloquante ne sera produite), alors pourquoi ne puis-je pas utiliser de récursions dans les fragments ? »

Un exemple de cette situation se produit chaque fois que nous utilisons un framework alimenté par GraphQL pour construire des sites statiques (comme Gatsby, Next.js ou RedwoodJS), car l'API GraphQL sera souvent privée, et nous ne pouvons pas faire accidentellement un DDoS de notre application et subir des conséquences négatives (au pire, elle plantera lors de la construction du site statique dans un environnement de développement ou de staging).

Les développeurs utilisant la configuration ci-dessus pourraient tout à fait se demander pourquoi la spec GraphQL leur interdit d'utiliser des fonctionnalités bénéfiques, qui n'ont aucune conséquence négative pour leur configuration.

En conclusion, en interdisant les fragments récursifs, la spec GraphQL impose une mesure de sécurité qui s'applique à une sélection de tous les usages potentiels de GraphQL, pas à tous, afin d'être du côté sûr.

​

La spec GraphQL pourrait-elle mieux satisfaire tous les acteurs ?

Si différents acteurs ont des exigences différentes, comment la spec GraphQL peut-elle les satisfaire tous ? (L'idée est d'éviter de forker la spec et de produire des versions personnalisées pour des cibles spécifiques.)

Explorons quelques idées, la première devant passer par le processus de contribution à la spec, tandis que la seconde ne le devrait pas.

​

Feature-toggle au niveau de la spec GraphQL

Une voie possible est que la spec « suggère » mais n'« impose » pas de règles. Dans ce cas, la règle interdisant les récursions dans les fragments pourrait être fortement suggérée, mais la fonctionnalité serait tout de même acceptée.

Or, cette solution changerait l'état par défaut des fragments récursifs de « obligatoire » à « optionnel », ce qui produirait deux conséquences négatives :

• L'API serait non sécurisée par défaut (le scénario que Lee Byron veut éviter)
• Cela produirait un breaking change, car une requête interdite serait alors autorisée

Il serait alors préférable d'inverser l'option, en maintenant les récursions dans les fragments toujours interdites par défaut mais en donnant la possibilité d'activer un feature-flag qui désactive ce comportement. Comme la fonctionnalité doit être explicitement désactivée, seuls les administrateurs qui savent ce qu'ils font le feront.

Comme la fonctionnalité est plus précieuse dans certaines configurations, les serveurs et frameworks GraphQL pourraient décider si/comment/quand proposer la configuration. Par exemple, Gatsby pourrait afficher de manière visible l'option via une interface lors de la création de sites statiques, et la masquer autrement.

L'idée générale est que la spec GraphQL supporte des « fonctionnalités activées mais optionnelles », pouvant être activées/désactivées via la configuration, et dont l'état par défaut est celui qu'elles ont déjà dans la spec.

Interdire les fragments récursifs en serait une, et il pourrait y avoir d'autres fonctionnalités similaires, comme un type Map, qui n'a pas été accepté dans la spec par Lee Byron parce que :

Il y a des compromis significatifs entre un type Map et une liste de paires clé/valeur. Un problème est la pagination sur la collection. Les listes de valeurs peuvent avoir des règles de pagination claires, tandis que les Maps qui ont souvent des paires clé-valeur non ordonnées sont beaucoup plus difficiles à paginer.

Un autre problème est l'utilisation. La plupart du temps, Map est utilisé dans les APIs où un champ de la valeur est indexé, ce qui est à mon avis un anti-pattern d'API car l'indexation est un problème de stockage et un problème de mise en cache côté client mais pas un problème de transport. Cet anti-pattern me préoccupe. Bien qu'il y ait de bonnes utilisations pour Maps dans les APIs, je crains que l'utilisation courante soit pour ces anti-patterns, je suggère donc de procéder avec prudence.

Lee Byron a exprimé sa crainte que la fonctionnalité soit utilisée comme un anti-pattern. Cependant, il a également reconnu qu'il en existe de bonnes utilisations. Alors, comme l'issue a recueilli beaucoup de soutien de la communauté (avec plus de 150 👍), les développeurs pourraient se voir donner la possibilité d'activer explicitement l'ajout d'un type Map à leurs schémas, et d'en gérer les conséquences.

​

Feature-toggle par les serveurs GraphQL

Si la proposition ci-dessus ne recueille pas de soutien car elle est trop risquée pour la spec GraphQL, une alternative est de l'implémenter au niveau du serveur GraphQL. Les serveurs GraphQL pourraient alors fournir une fonctionnalité personnalisée qui désactive les récursions dans les fragments.

En généralisant l'idée, les serveurs GraphQL pourraient proposer de désactiver certaines fonctionnalités de la spec, et d'en activer d'autres qui manquent à la spec. Pour que ce comportement ne produise pas de surprises, les serveurs doivent s'assurer que l'état par défaut est celui requis par la spec, et l'administrateur de l'API doit être pleinement conscient des conséquences de l'activation de la fonctionnalité. (C'est la stratégie suivie par Gato GraphQL pour ses « innovative features ».)

​

Conclusion

Alors que GraphQL est devenu de plus en plus populaire, de nouveaux frameworks supportant de nouvelles capacités en ont fait partie de leur stack, et de nouveaux acteurs (et de nouveaux types d'acteurs) se sont impliqués. Une spécification initialement créée par Facebook pour définir comment ses applications obtiendraient des données de ses serveurs doit de plus en plus faire face à davantage de cas d'usage.

Il est inévitable que des conflits surviennent, où un ensemble d'acteurs a besoin d'une fonctionnalité qui est contre-productive, voire préjudiciable, pour d'autres acteurs, comme c'est le cas avec les fragments récursifs. Que peut-on faire pour améliorer la situation et éviter que les acteurs insatisfaits ne soient déçus par GraphQL ?

J'ai soutenu que la spec pourrait offrir la possibilité de « désactiver » une fonctionnalité, permettant aux administrateurs qui savent ce qu'ils font de supprimer certaines limitations afin de satisfaire leurs propres exigences. Maintenant, je ne suis pas moi-même d'accord avec cette solution, mais je la mets sur la table néanmoins, car cette discussion doit avoir lieu. Comme cette idée est controversée, une meilleure alternative est que les serveurs GraphQL fournissent ce comportement via des fonctionnalités personnalisées, qui doivent être explicitement activées.