Initiation à GraphQL

resolvers.js :

const resolvers =  {
   Query: {
      hello: () => 'Hello world!'
   }
}
export default resolvers;

Voilà c’est tout :), maintenant il suffit de lancer le server :

npm i (si ce n'est pas déjà fait)
npm run dev
...
...
Server ready at https://localhost:4000

Je vous laisse tester votre requête, vous verrez que c’est assez intuitif. Pendant ce temps je vais vous faire un topo sur la partie client.

① C’est ici que nous allons définir nos query
② Ici la réponse de notre appel sera afficher
③ On trouvera dans cette zone, la description de notre schéma, en gros notre documentation

Maintenant que nous avons fait notre Hello world, nous allons passer au vif du sujet, faire une API en GraphQL. Comme source de données nous allons nous baser sur une API REST qui nous renvoie la liste des personnages de Game Of Thrones (oui il y en a beaucoup)

API Game Of Thrones

Configuration du client HTTP :

Tout d’abord nous allons installer un client Http afin de pouvoir faire des requêtes vers l’API REST. J’ai opté pour axios. Mettez-vous sur le projet (dossier start) et lancez cette commande => npm i axios. La dépendance va être automatiquement ajouté à votre package.json.

Maintenant on va créer un fichier js à la racine du dossier datasources, qu’on va nommer gameOfThronesApi.js ou ce que vous voulez, j’avoue que je ne suis pas très inspiré 😀

root
|───datasources
|    |gameOfThronesApi.js

Ce fichier va nous permettre de configurer notre client Http une seule fois et de le réutiliser pour tous les appels que nous allons faire vers cette API.

Passons à la configuration, pour cela, rajoutez ce code dans gameOfThronesApi.js :

// # gameOfThronesApi.js

const axios = require('axios');

module.exports = axios.create({
    baseURL: 'https://api.got.show/api/general'
});

Nous avons juste définie la baseURL, on peut aussi configurer d’autres choses, mais ce n’est pas le but de ce tuto, je vous laisse lire la documentation d’axios si vous avez envie d’en savoir un peu plus.

Maintenant que nous avons configuré notre client, nous allons pouvoir récupérer de la donnée. Nous allons implémenter un des DAO qui nous permettra de faire ça.

Implémentation d’un DAO

Nous allons modifier le fichier characters.js afin d’implémenter les méthodes d’accès aux données et mapper l’objet de retour en un objet interne :

const gameOfThronesApi = require('./gameOfThronesApi');

export default class Characters {

    async getAllCharacters() {
        const characters = await gameOfThronesApi.get('/characters');
        return Array.isArray(characters.data) ? characters.data.map(character => this.characterReducer(character)) : [];
    }

    characterReducer(character) {
        return {
            id: character._id || 0,
            male: character.male,
            house: character.house,
            slug: character.slug,
            name: character.name,
            books: character.books || [],
            titles: character.titles
        };
    }
}

Rien de bien fameux, on importe notre client HTTP gameOfThronesApi et dans la méthode getAllCharacters() on fait un get vers le endpoint /characters après ça on transforme l’objet de retour en un objet interne qui sera utilisé plus tard.

Donc là nous avons notre source de données, il ne reste plus qu’à la rendre disponible à travers GraphQL. Pour cela nous allons commencer par mettre à jour notre schéma.

Mis à jour du schéma GraphQL

Dans notre schéma nous allons définir nos objets de sortie ainsi que leur type en utilisant le GraphQL SDL :

type Query {
    characters : [Character]
}

type Character {
    id:       ID!,
    male:      Boolean
    house:     String,
    slug:      String,
    name:      String,
    books:     [String],
    titles:    [String]
}

Ici nous avons deux parties distinctes :

• type Query : C’est ici que nous définirons nos requêtes et ce sont ces requêtes qui seront déclarées dans nos resolvers, ici la requête characters nous renvoie une liste de types Character ([Character]). Ce type est défini plus bas.
• type Character : C’est un type d’objet GraphQL que nous avons créé qui est formé de fields ayant un type d’objets standard. Le seul type un peu “bizarre” est ID!, c’est pour définir l’identifiant unique de l’objet, le ! signifie que l’objet ne peut être null. Pour plus de détails, je vous conseille de lire cette documentation.

Maintenant que nous avons les sources de données et le format des objets de sortie, il nous reste juste à implémenter nos resolvers pour "mapper" la requête à la donnée.

Implémentation des resolvers

Chaque resolver accepte 4 arguments :

fieldName: (parent, args, context, info) => result

• parent : L’objet qui contient le résultat renvoyé par le resolver parent (nous ne l’utiliserons pas ici).
• args : Un objet qui contient les arguments passés dans la requête. Par exemple characters(name: "Aegon"), l’objet args aura pour valeur {"name": "Aegon"}.
• context : C’est un objet partagé par tous les resolvers, il peut contenir par exemple les informations d’authentification.
• info : Contient les informations sur le statut de l’exécution de la requête.

Pour le moment nous n’allons utiliser aucun de ces arguments, du coup on mettra des parenthèses vides 😀

// # resolvers.js
import Characters from './datasources/characters';

let characters = new Characters();

const resolvers =  {
    Query: {
        characters: async () => characters.getAllCharacters(),
    }
}

export default resolvers;

Ici on dit que pour la query characters il faut exécuter la fonction characters.getAllCharacters() tout simplement.

Relançons le server :

npm run dev
...
...
Server ready at https://localhost:4000

Vous pouvez tester vos requêtes en utilisant l’autocomplétion. Vous remarquerez que le client GraphQL vous impose de rentrer exactement les champs dont vous avez besoin et ce pour éviter de faire du over-fetching.

Vous constaterez aussi que l’on reçoit en retour exactement ce qu’on demande et on peut aussi aller un peu plus loin en changeant les noms des attributs de retour. Testez cette requête par exemple :

query {
    characters {
        nom: name
        livres: books
    }
}

Voici la réponse reçue :

'data': {
    'characters': [
        {
            'nom': 'Abelar Hightower',
            'livres': [
                'The Hedge Knight'
            ]
        },
        {
            'nom': 'Addam Frey',
            'livres': [
                'The Mystery Knight'
            ]
        },
        ...
    ]
}

Maintenant nous allons voir comment passer des arguments dans notre requête. Que faire si nous souhaitons faire une recherche par nom ? Tout d’abord nous allons implémenter la méthode qui fait cela dans character.js, toujours en utilisant l’API REST mais cette fois nous allons appeler ce endpoint :

// character.js
async getCharacterByName(name) {
    const characters = await gameOfThronesApi.get(/characters/${name});
    return this.characterReducer(characters.data.data);
}

Ensuite nous allons modifier notre Query GraphQL comme suit :

// schema.graphql
type Query {
    characters : [Character]
    character(name: String!) : Character
}

On passe tout simplement un argument non null de type String à notre requête et elle nous renvoie un objet de type Character.
Finalement, et c’est la partie la plus intéressante, nous allons ajouter un resolver dans resolver.js :

// resolver.js
const resolvers =  {
    Query: {
        characters: async (parent, args, context, info) => characters.getAllCharacters(),
        character: async (parent, {name}) => characters.getCharacterByName(name)
    }
}

On met notre argument en deuxième position dans notre liste d’argument et le tour est joué, nous pouvons faire nos requêtes :

query {
    character(name: 'Aegon Targaryen') {
        name
        male
        titles
    }
}

Et on reçoit la réponse :

{
    'data': {
        'character': {
            'name': 'Aegon Targaryen (son of Aenys I)',
            'male': true,
            'titles': [
                'Prince'
            ]
        }
    }
}

Vous remarquerez que l’API que nous utilisons ne fait pas réellement une recherche par nom, elle renvoie le premier personnage dans la liste et c’est tout, mais bon ce n’est pas le sujet 😀

Nous avons vu ce qu’était une Query GraphQL, elle nous permet de récupérer de la donnée (l’équivalent du GET en REST). Que faire si nous souhaitons modifier de la data ? Eh bien on utilise ce qu’on appelle les Mutations.

Mutation

Les mutations sont l’équivalent du POST, PUT et DELETE en REST. Elles sont utilisées pour écrire, modifier ou supprimer de la donnée. Regardons ensemble comment s’en servir.

D’abord, nous allons créer dans le dossier datasources un fichier houses.js qui contiendra une (petite) liste des maisons de Game of Thrones :

let houses = [
   { id: 1, name: 'House Stark', words: 'Winter is Coming' },
   { id: 2, name: 'House Targaryen', words: 'Fire and Blood' },
   { id: 3, name: 'House Baratheon', words: 'Ours is the Fury' },
   { id: 4, name: 'House Greyjoy', words: 'We Do Not Sow' },
];

export default houses;

Ensuite nous allons mettre à jour le schéma pour définir les requêtes qui nous permettront plus tard de modifier les données de cette liste :

//  schema.graphql
type Mutation {
    """
    Create a new house
    """
    createHouse(id: ID!, name: String!, words: String): [House]!,

    """
    Update an existing house
    """
    updateHouse(id: ID!, name: String!, words: String): [House]!,

    """
    Delete a house
    """
    deleteHouse(id: ID!): [House]!,
}

type House {
    id:       ID!,
    name:      String,
    words:      String
}

Vous remarquerez que j’ai rajouté des lignes entourées de """, c’est pour documenter notre API. Vous verrez cette description dans le client GraphQL, section "Schema".

Maintenant que tout est prêt nous allons implémenter nos resolvers :

// resolvers.js
const resolvers = {
    Query: {
        characters: async (parent, args, context, info) => characters.getAllCharacters(),
        character: async (parent, {name}) => characters.getCharacterByName(name),
        houses: () => houses
    },
    Mutation: {
        createHouse: (parent, {id, name, words}) => {
            let newHouse = {id, name, words};
            houses.push(newHouse);
            return houses;
        },
        updateHouse: (parent, {id, name, words}) => {
            let houseToUpdate = houses.find(house => house.id == id);
            houseToUpdate.name = name;
            houseToUpdate.words = words ? words : houseToUpdate.words;
            return houses;
        },
        deleteHouse: (parent, {id}) => {
            let houseIndex = houses.findIndex(house => house.id == id);
            console.log(houses)

            if (houseIndex === -1) {
                throw new Error('House not found.');
            }

            return houses;
        }
    }
}

Nous avons créé un nouvel attribut Mutation qui contient nos resolvers avec les arguments que nous définirons en entrée.

Lançons notre server (npm run dev) et regardons ce que cela donne avec la requête suivante :

mutation{
    createHouse(id: 5, name: 'House SOAT', words: 'In sharing we trust'){
        name
        words
    }
}

Résultat :

{
    'data': {
        'createHouse': [
            {
                'name': 'House Stark',
                'words': 'Winter is Coming'
            },
            {
                'name': 'House Targaryen',
                'words': 'Fire and Blood'
            },
            {
                'name': 'House Baratheon',
                'words': 'Ours is the Fury'
            },
            {
                'name': 'House Greyjoy',
                'words': 'We Do Not Sow'
            },
            {
                'name': 'House SOAT',
                'words': 'In sharing we trust'
            }
        ]
    }
}

On voit bien qu’une nouvelle maison a été ajouté.

Conclusion

Nous avons créé un serveur GraphQL, utilisé les Query pour récupérer de la donnée et les Mutations pour modifier ces données. Nous avons également vu les avantages de GraphQL par rapport à REST, notamment le fait de récupérer exactement ce que l’on souhaite en un seul appel. Plus de over-fetching ni de N+1 call.

Pour aller plus loin je vous conseille le tuto sur le site d’Apollo. Apollo étant une implémentation de GraphQL permettant la création d’un client/serveur, d’ailleurs Graphpack est basé dessus.
Nous verrons d’autres aspects plus poussés dans un prochain article, stay tuned 😉

© SOAT
Toute reproduction interdite sans autorisation de l’auteur.