🛠 WordPress devrait-il avoir une API GraphQL dans le core ?

WordPress 5.7 arrive bientôt. Comme c'est le cas depuis de nombreuses versions, la WP REST API apportera également plusieurs nouvelles fonctionnalités.

Parmi les nouvelles fonctionnalités, l'une a retenu mon attention : "Image Editor Accepts a List of Modifiers".

L'endpoint /wp/v2/media/<id>/edit introduit dans WordPress 5.5 était livré avec une API limitée qui acceptait des déclarations de rotation et de recadrage de niveau supérieur. Dans 50124, cette API a été rendue plus puissante et flexible en acceptant un tableau de modifications dans le nouveau paramètre de requête modifiers.

import apiFetch from '@wordpress/api-fetch';
 
const data = {
  modifiers: [
    {
      type: 'crop',
      args: {
        left  : 0,
        top   : 0,
        width : 80,
        height: 80
      }
    },
    {
      type: 'rotate',
      args: {
        angle: 90
      }
    }
  ]
};
apiFetch( { data, method: 'POST', path: '/wp/v2/media/5/edit' } );Copy

Ce développement a pris un certain temps.

D'abord, dans WordPress 5.5, l'endpoint d'édition d'images a été introduit.

Cet endpoint était initialement assez rigide, nécessitant de passer toutes les données ensemble concernant toutes les opérations à appliquer sur l'image. Par exemple, pour faire pivoter l'image et modifier sa taille, on passerait ces données :

{
  "x": 0,
  "y": 0,
  "width": 80,
  "height": 80,
  "rotate": 90
}Copy

Ensuite, dans WordPress 5.6, les opérations en lot ont été introduites dans la WP REST API.

Enfin, dans la prochaine version WordPress 5.7, les opérations à appliquer sur l'image ont été découplées, nous avons donc les opérations "crop" et "rotate". Ces opérations peuvent être exécutées séparément, mais aussi ensemble dans la même requête via le traitement par lot.

Comme vu précédemment, passer des données à l'endpoint est maintenant beaucoup plus élégant :

{
  "modifiers": [
    {
      "type": "crop",
      "args": {
        "left"  : 0,
        "top"   : 0,
        "width" : 80,
        "height": 80
      }
    },
    {
      "type": "rotate",
      "args": {
        "angle": 90
      }
    }
  ]
}Copy

​

Refaire ce qui existe déjà ?

La WP REST API n'est pas la seule API pour WordPress. Il existe (au moins) deux alternatives :

• GraphQL, via WPGraphQL
• GraphQL + persisted queries, via Gato GraphQL
  (☝🏽 C'est moi, votre hôte pour cet article de blog ☝🏽)

GraphQL est un type d'API relativement récent, qui excelle dans les opérations en lot. En utilisant GraphQL, il n'est pas nécessaire de passer du temps et de l'énergie à développer une solution personnalisée pour celles-ci, comme c'est le cas avec REST.

En effet, on pourrait voir REST comme "copiant" cette fonctionnalité de GraphQL.

Prendre en charge les opérations en lot dans la WP REST API a pris au moins 2, voire 3, cycles de version à accomplir. Ce n'est pas une quantité de temps négligeable, et cela a nécessité la contribution de plusieurs personnes.

Si WordPress pouvait également utiliser GraphQL, et que l'endpoint d'édition d'images était basé sur GraphQL plutôt que sur REST, alors ces contributeurs pourraient travailler sur d'autres développements.

WordPress ne serait-il pas mieux loti, et développé beaucoup plus rapidement, s'il pouvait utiliser les meilleures qualités de chaque API, selon ce qui est le plus pratique ?

​

Opérations en lot dans GraphQL

Je vais vous montrer non pas une, mais plusieurs façons dont Gato GraphQL prend en charge les opérations en lot.

La première est la plus simple : ajouter plusieurs champs à la racine de la requête. Par exemple, cette requête connecte l'utilisateur, puis ajoute un commentaire :

mutation LogUserInAndAddCommentToPost {
  loginUser(
    by: { credentials: { usernameOrEmail: "test", password: "pass" } }
  ) {
    id
    name
  }
  addCommentToCustomPost(
    input: {
      customPostID: 1459
      commentAs: { html: "Adding a comment: bla bla bla" }
    }
  ) {
    id
    content
    date
  }
}Copy

(Au fait, il s'agit du client GraphiQL. Voici un tutoriel sur son utilisation.)

Ces deux opérations ont été appliquées sur des objets différents, mais nous souhaitons appliquer plusieurs opérations sur le même objet.

Faisons cela maintenant : cette requête ajoute deux commentaires au même article.

mutation AddTwoCommentsToPost {
  firstComment: addCommentToCustomPost(
    input: {
      customPostID: 1459
      commentAs: { html: "This is my first response" }
    }
  ) {
    id
    content
    date
  }
  secondComment: addCommentToCustomPost(
    input: {
      customPostID: 1459
      commentAs: { html: "This is my second response" }
    }
  ) {
    id
    content
    date
  }
}Copy

Ces deux commentaires ont été ajoutés à un article déjà existant. Mais que se passerait-il si l'article devait également être créé en premier ?

Dans ce cas, la requête simple ne fonctionnera plus, car nous ne connaissons pas l'ID de l'article à créer, qui est nécessaire comme argument pour les autres opérations (remarquez le ? dans l'argument du champ) :

mutation CreatePostAndAddTwoCommentsToPost {
  createPost(input: { title: "Some post" }) {
    id  # <= I don't know what this value will be
  }
  addCommentToCustomPost(input: {
    customPostID: ?,
    commentAs: { html: "Blah blah blah" }
  }) {
    id
    content
    date
  }
}Copy

Mais ne désespérez pas, Gato GraphQL vous couvre. Il propose non pas une, mais deux solutions !

La première consiste à utiliser la fonctionnalité d'exécution de requêtes multiples.

Dans cette requête, nous exécutons la première opération, exportons son résultat via la directive @export, puis injectons cette valeur comme entrée dans la deuxième requête :

mutation AddComment {
  addCommentToCustomPost(
    customPostID: 1459
    commentAs: { html: "Some insightful comment" }
  ) {
    id @export(as: "newCommentID")
    content
    date
  }
}
 
mutation AddResponseToComment @depends(on: "AddComment") {
  replyComment(
    parentCommentID: $newCommentID
    commentAs: { html: "Debunking your insightful comment" }
  ) {
    id
    date
    content
    parent {
      id
    }
  }
}Copy

Plus élégant encore, nous pouvons utiliser les mutations imbriquées.

Dans cette requête, nous exécutons la première opération et imbriquons la deuxième opération à l'intérieur, de sorte qu'elle sera appliquée à l'objet créé lors de la première opération (puis en répétant, en imbriquant une 3e opération, et ainsi de suite) :

mutation AddCommentAndResponseAndResponse {
  addCommentToCustomPost(
    input: {
      customPostID: 1459
      commentAs: { html: "Some insightful comment" }
    }
  ) {
    id
    content
    date
    reply(input: { commentAs: { html: "Debunking your insightful comment" } }) {
      id
      date
      content
      parent {
        id
      }
      reply(input: { commentAs: { html: "No, it was right!" } }) {
        id
        date
        content
        parent {
          id
        }
      }
    }
  }
}Copy

En bonus, les opérations en lot peuvent être appliquées non seulement sur une seule entité, mais sur plusieurs entités en même temps, dans la même requête.

Dans cette requête, les nouveaux commentaires et toutes leurs réponses sont ajoutés à plusieurs articles :

mutation AddCommentAndResponseToManyPosts {
  posts(ids: [1657, 1153, 1499, 1459]) {
    id
    addComment(input: { commentAs: { html: "Some insightful comment" } }) {
      id
      content
      date
      reply(
        input: { commentAs: { html: "Debunking your insightful comment" } }
      ) {
        id
        date
        content
        parent {
          id
        }
      }
    }
  }
}Copy

Et le plugin a encore un tour dans sa manche : en utilisant la fonctionnalité de champs intégrables, nous pouvons personnaliser le contenu passé à chaque argument de champ, en utilisant les données de l'objet lui-même !

Dans cette requête, les commentaires contiennent des informations de l'objet sur lequel ils sont créés :

mutation AddCustomCommentAndResponseToManyPosts {
  posts(ids: [1657, 1153, 1499, 1459]) {
    id
    addComment(
      input: {
        commentAs: { html: "The post has ID {{ id }} and title {{ title }}" }
      }
    ) {
      id
      content
      date
      reply(
        input: {
          commentAs: {
            html: "The parent comment was posted on {{ dateStr(format: \"d/m/Y\") }}. Cool, right?"
          }
        }
      ) {
        id
        date
        content
        parent {
          id
        }
      }
    }
  }
}Copy

​

Tirer le meilleur de REST et GraphQL selon les besoins

À mesure que Full Site Editing est développé et étendu, WordPress dépendra de plus en plus de ses API.

Concernant les fonctionnalités existantes, la REST API s'est très bien comportée jusqu'à présent. Il n'est pas nécessaire de reconstruire ce qui fonctionne.

Cependant, concernant les nouvelles fonctionnalités encore à développer, WordPress ne bénéficierait-il pas de l'utilisation de REST ou GraphQL, selon ce qui est le plus pratique pour cette fonctionnalité spécifique ?

La réponse vous appartient...