🕸 Comment et où GraphQL peut améliorer WordPress, en complément de la REST API

Le week-end dernier, j'ai publié l'article de blog 🦸🏿‍♂️ Gato GraphQL est maintenant transpilé de PHP 8.0 à 7.1.

Après avoir partagé le post sur Reddit's /r/php, la communauté a lancé une discussion animée sur l'intérêt d'utiliser GraphQL dans WordPress, en quoi il diffère de la WP REST API, et dans quelle mesure il est justifié d'apporter une nouvelle API à WordPress.

Je pense que la plupart des commentaires sont pertinents, et que d'autres manquent d'informations clés. GraphQL n'est pas seulement une interface, mais aussi une implémentation. Cela signifie que différents serveurs GraphQL, de différents fournisseurs, peuvent avoir été conçus pour prioriser différentes caractéristiques. En tant que tel, nous ne pouvons pas toujours avoir une attente unifiée de ce que GraphQL offre, ou une compréhension complète du fonctionnement d'un moteur GraphQL.

Par exemple, l'expérience GraphQL dans WordPress et dans Laravel sera différente, tout comme l'expérience fournie par les différents serveurs, WPGraphQL ou Gato GraphQL.

Cet article est mon point de vue sur le sujet, répondant à plusieurs des commentaires du post Reddit.

​

GraphQL vs WP REST API

[C'est une si mauvaise idée] d'avoir une API GraphQL par-dessus WordPress qui utilise déjà sa propre REST API. Utilisez simplement la REST API. [Source]

La REST API et GraphQL servent le même objectif : fournir à l'application les données dont elle a besoin. Cependant, ils se comportent différemment dans la façon dont ils y parviennent : alors que REST a des endpoints prédéfinis fournissant un ensemble spécifique de données, GraphQL peut fournir exactement les données nécessaires.

Ce comportement différent peut avoir un impact direct sur les performances de l'application. Avec REST, si nous avons besoin de récupérer une liste d'articles plus des données de chaque auteur de l'article, cela nécessitera l'envoi de requêtes supplémentaires. Peut-être 1 requête supplémentaire pour toutes les données d'auteur, ou 1 requête supplémentaire par auteur. Entre-temps, le visiteur du site web peut attendre que la page soit rendue.

GraphQL améliore cette situation, car nous pouvons directement récupérer toutes les données d'articles et d'auteurs en une seule requête, et le rendu de la page web sera plus rapide :

{
  posts {
    id
    title
    excerpt
    date
    url
    author {
      id
      name
      url
    }
  }
}Copy

Ainsi, même si nous avons déjà la REST API dans WordPress, cela ne signifie pas qu'elle est toujours l'outil le plus adapté à chaque tâche. Bien sûr, nous pouvons toujours l'utiliser, mais si nous avons également accès à GraphQL, alors nous pouvons décider d'utiliser cette API chaque fois qu'elle offre un avantage sur REST, et nous en sortirons mieux.

​

Configuration initiale difficile pour GraphQL + Devoir écrire des resolvers

Il y a certainement un argument selon lequel la configuration initiale pour GraphQL est exponentiellement plus élevée que pour REST ; vous avez raison que les associations doivent être configurées. [Source]

Et...

Ce que vous et presque tout le monde sur le web omettez, c'est que pour que ce format d'API fonctionne, vous devez écrire le parser (resolvers + types) qui apporte une série de problèmes qui ne sont pas présents avec REST. [Source]

Ces commentaires ne sont pas complètement exacts, car WPGraphQL et Gato GraphQL ont déjà mappé le modèle de données WordPress dans le schéma GraphQL (WPGraphQL entièrement, mon plugin pour la plupart).

Ensuite, après avoir installé l'un de ces plugins, vous pouvez immédiatement commencer à récupérer des données pour votre application, sans avoir besoin de créer des resolvers, ou de configurer des associations entre entités.

Il est vrai que, pour récupérer des données personnalisées des entités propres à l'application (comme les CPTs), celles-ci doivent être mappées via des resolvers, et vous devrez le faire. Mais ce n'est pas différent de REST : si vous avez besoin de données personnalisées de votre CPT, vous devrez créer un endpoint REST pour récupérer ces données personnalisées. Un endpoint personnalisé est aussi un resolver.

Ainsi, concernant le besoin de resolvers, REST et l'API GraphQL sont pratiquement identiques.

Maintenant, en parcourant des sites web et de la documentation, cela donne l'impression que GraphQL nécessite plus d'effort de configuration. Il y a donc une part de vérité dans cette présomption.

Je crois qu'il y a quelques raisons à cela. Premièrement, GraphQL implique (au moins) deux parties :

1. le concept de ce que c'est, et comment ça fonctionne
2. les serveurs fournissant une implémentation réelle

En parcourant la documentation de GraphQL, comme le site officiel graphql.org, elle se concentre sur les concepts derrière GraphQL, entrant dans les détails des resolvers, ce qu'ils sont et pourquoi ils sont nécessaires.

C'est utile lorsque vous construisez une application de zéro, comme si vous utilisez Laravel et Lighthouse. Dans ce cas, vous avez besoin de coder vos resolvers (mais vous auriez aussi besoin de créer vos endpoints REST).

Cependant, WordPress est déjà l'application, et WPGraphQL et Gato GraphQL sont des solutions. Ces deux plugins ont déjà créé les resolvers pour nous, donc nous n'avons pas à nous en inquiéter (de la même façon que la WP REST API fournit également un ensemble initial d'endpoints, donc nous n'avons pas à nous en inquiéter).

De plus, GraphQL est plus centré sur les développeurs, et sa documentation semble s'adresser directement aux développeurs. Les développeurs créent les resolvers côté serveur, et les développeurs consomment ces resolvers avec des requêtes personnalisées côté client. Puisque construire des resolvers est une tâche pour les développeurs, cela apparaît naturellement et souvent.

Pour REST, l'attente (je crois) est que l'endpoint fournissant les données requises existera déjà (comme livré par la WP REST API). Si ce n'est pas le cas, seulement alors nous devons nous préoccuper de configurer un endpoint personnalisé. Ainsi, il y a moins d'emphase sur la création de resolvers pour REST.

Ainsi, REST et GraphQL fournissent tous deux les données requises. Mais alors que REST encourage une approche statique, où les endpoints devraient déjà exister, et seulement quand ils n'existent pas nous nous en inquiétons, GraphQL encourage une approche dynamique, où chaque requête est faite sur mesure, et nous pouvons alors coder le resolver parfait pour elle.

Donc, en fin de compte, il n'y a pas de différences fondamentales entre REST et GraphQL, juste des interprétations différentes sur la façon dont ils doivent satisfaire leurs exigences.

​

Vulnérabilités + Considérations de sécurité dans GraphQL

Nous allons voir une énorme vulnérabilité de GraphQL un jour, car écrire des interpréteurs sécurisés est vraiment difficile. [Source]

Et...

WordPress est déjà si massif qu'il a déjà une énorme cible dans le dos ; ajouter N'IMPORTE QUEL plugin ajoute beaucoup de risques, et un plugin offrant d'exposer littéralement tout WordPress, y compris des nombreux exemples de code pour contourner le modèle de sécurité, c'est un grand non pour moi. La sortie non pilotée par le thème devrait être aussi restreinte que possible (inexistante à moins que je ne le demande) au-delà de ce qui est absolument nécessaire d'exposer. J'espère que cela ne sera jamais intégré dans le core. [Source]

GraphQL impose en effet des risques de sécurité supplémentaires que nous devons aborder. Je suis entièrement d'accord avec ce sentiment.

Mais je ne pense pas que ce soit un problème aussi bloquant, au point d'empêcher une inclusion potentielle de GraphQL dans le core de WP. De plus, je ne pense même pas que ce soit vraiment difficile à résoudre.

Ce qui est nécessaire, c'est que le serveur GraphQL exploite les mécanismes de sécurité existants de WordPress, puis que le développeur utilise ces mécanismes, en s'assurant qu'un champ ne peut être accessible que par les utilisateurs appropriés :

• l'utilisateur est-il connecté ?
• l'utilisateur est-il l'administrateur ?
• l'utilisateur a-t-il un certain rôle ou une certaine capacité ?
• l'utilisateur est-il l'auteur de l'article ?

Pour satisfaire cette proposition, Gato GraphQL offre des Listes de contrôle d'accès, afin que nous puissions définir qui peut accéder à chaque champ et directive, et par configuration.

Maintenant, parfois utiliser une ACL seule ne suffit pas, et le serveur GraphQL doit fournir des mesures de sécurité supplémentaires. Je vais décrire sur quoi je travaille en ce moment pour la prochaine v0.8 de Gato GraphQL.

Le champ posts (pour récupérer des données d'articles) ne nécessite pas d'autorisation, n'importe quel utilisateur peut y accéder, qu'il soit connecté ou non. Ainsi, pour des raisons de sécurité, il ne récupère que les articles publiés.

Mais il y a des situations où nous avons besoin de récupérer aussi des articles en brouillon/en attente/supprimés, comme :

• Pour construire un site web statique, qui est exécuté par l'administrateur, avec accès à toutes les données du site
• Pour les auteurs de l'article, pour lister tous les brouillons afin qu'ils puissent continuer à les modifier

J'ai alors élaboré le schéma suivant. Pour récupérer des articles, il y aura 3 champs :

• posts : ouvert à tout le monde, peut seulement récupérer des articles publiés
• myPosts : ouvert à tout le monde, récupère seulement les articles de l'utilisateur connecté, avec n'importe quel statut (publié/brouillon/en attente/supprimé)
• postsForAdmin : seul l'administrateur peut y accéder, récupère n'importe quel article avec n'importe quel statut

Et ensuite, postsForAdmin est désactivé par défaut, donc il n'apparaît même pas dans le schéma GraphQL, à moins que l'administrateur ne l'active explicitement (et, très probablement, il ne sera activé que pour construire des sites statiques).

Une autre situation est lorsqu'un champ peut récupérer à la fois des données publiques et privées. Par exemple, le champ option récupère des données de la table wp_options. Certaines entrées sont publiques (comme blogname), tandis que d'autres ne le sont pas (comme admin_email).

Une situation similaire concerne la récupération des valeurs méta, via les champs Post.metaValue, User.metaValue, et autres. Par exemple, les métas utilisateur incluent l'entrée wp_capabilities, qui est certainement privée, tandis que description est publique. Et puis il y a last_name, qui peut être public ou privé selon l'application.

Pour rendre l'accès à ces données sécurisé, le plugin permettra de spécifier quelles entrées peuvent être interrogées via une liste d'autorisation/refus dans la page des paramètres, acceptant à la fois l'entrée complète ou une regex :

Ensuite, interroger l'option autorisée fonctionnera, tandis que l'option refusée retournera simplement null :

{
  # This option is allowed
  siteName: optionValue(name: "blogname")
  # This optionValue is not allowed
  adminEmail: optionValue(name: "admin_email")
}Copy

Avec des mesures de sécurité appropriées fournies par le serveur GraphQL, et le bon sens du développeur, créer une API GraphQL sécurisée ne devrait pas être difficile.

​

GraphQL faisant tomber la BDD

GraphQL est une syntaxe riche permettant d'exprimer des requêtes relationnelles profondes, donc pour un écosystème comme WordPress, où l'extensibilité du modèle de données provient du pattern entity-attribute-value, cela se traduit par des quantités incroyables d'usure sur une base de données, ce qui peut rendre votre site non réactif si la requête GraphQL est profonde, compliquée ou récursive. WordPress est déjà célèbre pour sa capacité à mettre une instance MySQL/MariaDB à genoux, donc ajouter GraphQL pourrait rendre les choses bien pires si les requêtes ne sont pas correctement écrites, authentifiées et limitées en débit. [Source]

Faire tomber la BDD est une préoccupation sérieuse pour les serveurs GraphQL. Je vais décrire comment Gato GraphQL tente d'éviter ce scénario.

Gato GraphQL évite que le problème N+1 se produise, déjà par conception architecturale. Il y parvient en rendant le moteur responsable du chargement des entités depuis la base de données, pas le développeur.

Lors de la résolution de connexions dans un resolver, la valeur retournée est l'ID (ou liste d'IDs) du/des objet(s), et non l'objet lui-même. Par exemple, récupérer l'auteur du custom post se fait ainsi :

class CustomPostFieldResolver extends AbstractDBDataFieldResolver
{
  private CustomPostUserTypeAPIInterface $customPostUserTypeAPI;
 
  public function getClassesToAttachTo(): array
  {
    return [
      CustomPostFieldInterfaceResolver::class,
    ];
  }
 
  public function getSchemaFieldType(string $fieldName): ?string
  {
    return match($fieldName) {
      'author' => SchemaDefinition::TYPE_ID,
      default => null,
    };
  }
 
  public function resolveValue(
    TypeResolverInterface $typeResolver,
    object $customPost,
    string $fieldName,
    array $fieldArgs = []
  ): mixed {
    switch ($fieldName) {
      case 'author':
        return $this->customPostUserTypeAPI->getAuthorID($customPost);
    }
 
    return null;
  }
 
  public function resolveFieldTypeResolverClass(
    TypeResolverInterface $typeResolver,
    string $fieldName
  ): ?string {
    switch ($fieldName) {
      case 'author':
        return UserTypeResolver::class;
    }
 
    return null;
  }
}Copy

Disposant de l'ID de l'entité BDD depuis resolveValue, et du type de l'objet depuis resolveFieldTypeResolverClass (représenté via la classe UserTypeResolver), le moteur GraphQL peut alors charger les données de l'objet.

Pour charger les données, le moteur utilise un algorithme super efficace : il a une complexité temporelle O(n), où n est le nombre de types dans la requête, pas le nombre de nœuds.

L'algorithme atteint cette efficacité car il ne parcourt pas un graphe, mais il convertit la structure de données en une pile de composants, qui est beaucoup plus simple à résoudre. (Le « graph » dans GraphQL est un concept, pas une implémentation réelle.)

Ainsi, même si la requête a plusieurs niveaux, chacun récupérant de nombreuses entités, l'algorithme peut toujours le gérer assez bien. Par exemple, il n'y a pas grand impact lors de l'exécution de la requête suivante, qui a une profondeur de 10 niveaux :

{
  posts(pagination: { limit: 10 }) {
    excerpt
    title
    url
    author {
      name
      url
      posts(pagination: { limit: 10 }) {
        title
        tags(pagination: { limit: 10 }) {
          slug
          url
          posts(pagination: { limit: 10 }) {
            title
            comments(pagination: { limit: 10 }) {
              content
              date
              author {
                name
                posts(pagination: { limit: 10 }) {
                  title
                  url
                  comments(pagination: { limit: 10 }) {
                    content
                    date
                    author {
                      name
                      username
                      url
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}Copy

L'exception à cette efficacité est lors de la récupération de valeurs méta, via Post.metaValue, User.metaValue, Comment.metaValue, PostTag.metaValue et PostCategory.metaValue (et aussi leur champ metaValues). C'est parce que les fonctions WordPress (get_post_meta, get_user_meta, etc) récupèrent des données pour 1 ID à la fois, ce qui signifie que chaque entité nécessitera un appel à la base de données pour récupérer sa valeur méta. En conséquence, la résolution des valeurs méta monte en fonction du nombre de nœuds, pas du nombre de types (le commentaire de l'OP fait mouche, à cet égard).

Pour éviter que des acteurs malveillants utilisent et abusent des champs méta, Gato GraphQL (en v0.8) sera livré avec ces champs désactivés par défaut. Ensuite, l'administrateur doit les activer explicitement et, ce faisant, peut placer ces champs sous une Liste de contrôle d'accès, de sorte qu'à aucun moment la BDD ne soit à risque d'attaque.

Le rate limiting est aussi une excellente idée, je prévois de le supporter pour une prochaine version.

Et puis il y a l'analyse et l'imposition de limitations sur la complexité de la requête (comme le nombre de niveaux en profondeur). Le serveur GraphQL résout la requête avec une complexité temporelle O(n), donc il n'y a pas grand dommage qui puisse être fait concernant les boucles. Cependant, une seule requête pourrait tout de même récupérer des quantités illimitées de données depuis la BDD, et c'est quelque chose que nous pourrions vouloir éviter.

Par exemple, cette simple requête apportera une quantité énorme de données en une seule requête (mon site de démo a à peine quelques centaines d'enregistrements, donc je peux me permettre de démontrer l'exécution de la requête) :

{
  posts000: posts(pagination: { limit: 100 }) {
    ...PostFields
  }
  posts100: posts(pagination: { limit: 100, offset: 100 }) {
    ...PostFields
  }
  posts200: posts(pagination: { limit: 100, offset: 200 }) {
    ...PostFields
  }
  posts300: posts(pagination: { limit: 100, offset: 300 }) {
    ...PostFields
  }
  posts400: posts(pagination: { limit: 100, offset: 400 }) {
    ...PostFields
  }
  posts500: posts(pagination: { limit: 100, offset: 500 }) {
    ...PostFields
  }
  posts600: posts(pagination: { limit: 100, offset: 600 }) {
    ...PostFields
  }
  posts700: posts(pagination: { limit: 100, offset: 700 }) {
    ...PostFields
  }
  posts800: posts(pagination: { limit: 100, offset: 800 }) {
    ...PostFields
  }
  posts900: posts(pagination: { limit: 100, offset: 900 }) {
    ...PostFields
  }
}
 
fragment PostFields on Post {
  id
  title
  content
  date
}Copy

Comme on peut le constater, la requête n'a même pas besoin d'être imbriquée pour créer des problèmes. Donc analyser la complexité d'une requête est une affaire délicate, qui nécessitera un réglage fin pour être utile.

J'espère supporter aussi l'analyse des requêtes, mais ce n'est pas dans ma liste de priorités élevées, car avec une combinaison des autres fonctionnalités (comme les persisted queries ou les custom endpoints, couplés avec des Listes de contrôle d'accès) nous pouvons déjà tenir les acteurs malveillants à l'écart, et nous-mêmes ne devrions pas (ne devrions pas !) abuser de notre propre service GraphQL.