SPIP GraphQL

1. But

Exposer un endpoint graphQL avec les données de SPIP grâce à la bibliothèque graphql-php

2. Fonctionnement du plugin

• Création d 'une table meta_graphql pour stocker les informations de configuration du plugin
• Expose un point d'entrée unique sur spip.php?action=graphql grâce à la librairie graphql-php. Ce fichier prépare le contexte et lance le serveur graphQL en attente des requêtes. Nul besoin du plugin http !
• Toute la logique de l'API se situe dans le dossier /schema

3. Fonctionnement de l'API

a. Apprendre graphQL

Si vous ne connaissaez pas graphQL, voici la documentation.

b. Les types disponibles

Les requêtes graphQL sont fortement typées. Les types sont créés dynamiquement en fonction des objets éditoriaux que vous aurez sélectionnés dans le Back-Office.

Grâce au schéma d'introspection, les clients peuvent afficher les types de données disponibles. Voici les types actuellement disponibles :

• Les types de bases (scalaires) : ID, String, Int, Boolean
• Le type scalaire personnalisé Date qui permet d'indiquer le format des dates attendu
• Le type MetaList qui représente les metas exposées
• Le type ENUM Collection pour récupérer les collections exposées
• Le type Interface Node utilisé par tous les objets. Ce type expose les champs id, slug, typeCollection, points et rang
• Le type Interface Objet utilisé par les objets éditoriaux (sauf Auteurs et Syndic). Ce type expose les champs id, titre, texte, slug, typeCollection, points, rang et maj
• Les types MonObjet liés aux objets éditoriaux (implémentant Objet ou non). Le champs points (et non le shampooing :p ) sert lors de la requête recherche. Il y a aussi le champ slug, le champ type (il existe aussi le champ __typeName fourni par graphQL) et le champ rang qui ont été ajoutés.

c. Les requêtes disponibles

Les requêtes disponibles sont aussi affichées par les clients grâce au schéma d'introspection. Le client JS intégré au plugin (ou votre extension navigateur) utilise ce schéma pour afficher les requêtes disponibles. Pour le moment, les requêtes disponibles sont :

• getMetas
• getCollections
• recherche qui prend un paramètre texte
• maCollection et getMonObjet pour chaque collection exposée

Les requêtes getMonObjet reçoivent un id en paramètre et les requêtes maCollection peuvent recevoir les paramètres suivants :

• where (un tableau de string comme ['id_rubrique=1','id_trad=2'])
• pagination pour indiquer le nombre d'items dans la pagination
• page pour indiquer la page voulue dans la pagination

4. Tester les requêtes

Le endpoint est joignable sur spip.php?action=graphql

Vous pouvez utiliser graphiql qui est intégré dans le plugin ou une extension pour votre navigateur. Concernant Firefox, j'utilise Altair GraphQL Client. A part pour le client intégré qui pointe directement sur votre endpoint, il faut renseigner l'url complète de votre API : http://domain.local/spip.php?action=graphql

Voici un exemple de requête graphQL que vous pouvez tester :

{
  getMetas {
    nom_site
  }
  articles(
    where: ["id_rubrique=3", "maj>2023-05-19 11:00:00"]
    page: 1
    pagination: 5
  ) {
    ...objetFields
  }
  getArticle(id:2) {
    ...objetFields
    auteurs (where: ["bio!=''"]) {
      nom
      email
      bio
    }
    pensebetes {
      ...objetFields
    }
  }
}

fragment objetFields on Objet {
  id
  titre
  texte
  maj
}

Pour la recherche, voici un exemple :

query  {
  recherche(texte: "Hello") {
    ... on Article {
      id
      slug
      titre
      texte
      maj
      points
    }
    ... on Auteur {
      id
      nom
      points
    }
  }
}

Si vous activez le jeton, vous devez l'intégrer dans l'en-tête de vos requêtes.

Par exemple avec le client graphiql intégré dans le back-office :

Pour utiliser des variables dans vos clients, voici la manière recommandée pour pouvoir facilement injecter, par ex, une saisie utilisateur dans la requête :

5. Contribuer

N'hésitez pas à contribuer : le code est extrêmement bien commenté

Pré-requis

• Avoir un site SPIP fonctionnel avec des objets éditoriaux.
• Avoir installé composer.
• Activez le mode debug du plugin pour récupérer les erreurs PHP dans la réponse de l'API.
• En cas d'ajout ou de suppression de fichier dans le dossier schema, lancez la commande composer update pour prendre en compte vos modifications.

Lien vers la documentation de la librairie graphql-php

https://webonyx.github.io/graphql-php/