GraphQL

La particularité de GraphQL est que la structure de la réponse du serveur est fixée par le client (conformément aux limites de l'API). Par exemple, c'est lui qui décide des champs qu'il souhaite pour chaque Objet, et dans quel ordre il veut les recevoir.

Prenons la situation d'un fournisseur de fruits & légumes. Il dispose d'une API GraphQL lui permettant d'obtenir toutes les commandes qu'on lui a effectué et leurs détails. Lorsqu'il consulte sa plateforme de gestion, son navigateur adresserait la requête suivante via la méthode POST :

{
    orders {
        id
        productsList {
            product {
                name
                price
            }
            quantity
        }
        totalAmount
    }
}

Après traitement de la réponse par l'API (dont le client n'a pas forcément connaissance), le serveur répondrait comme suit :

{
    "data": {
        "orders": [
            {
                "id": 0,
                "productsList": [
                    {
                        "product": {
                            "name": "orange",
                            "price": 1.5
                        },
                        "quantity": 100
                    }
                ],
                "totalAmount": 150
            }
        ]
    }
}

Dans cet exemple, un produit peut posséder beaucoup plus d'attributs que simplement le nom et le prix. Mais dans notre situation, le fournisseur n'a pas besoin de plus d'informations que ça. De cette manière, l'utilisation de GraphQL a permis au client de se passer des informations inutiles, et donc de gagner du temps et des ressources. Le problème de données surnuméraires, dit over-fetching, a ainsi été évité. De même, l'API GraphQL a garanti l'obtention de toutes les informations nécessaires à la consultation du fournisseur, ce qu'une API REST n'aurait pas forcément permis en une requête seulement. Cette fois, c'est le problème de données insuffisantes, ou under-fetching, qui a été évité.

Une API GraphQL est organisée grâce aux Types et Champs. Pour déclarer l'ensemble de ces éléments, le fournisseur de données doit construire le squelette de l'API. C'est ce schéma qu'il partagera avec tous les clients qu'il souhaite, sans qu'ils aient besoin de savoir comment les données ont été récupérées. Dans l'exemple précédent, le schéma pourrait être celui-ci :

type Query {
    orders: [Order]
}
type Product {
    id: Int!
    name: String
    weight: Float
    price: Float
}
type Order {
    id: Int!
    productsList: [
        product: Product
        quantity: Int
    ]
    totalAmount: Int
}

Structure en graphe d'une réponse à une requête GraphQL.

Le premier Type, Query, contient toutes les requêtes de consultation admises par l'API. Dans l'exemple, on retrouve la règle orders, qui permet de recevoir un ensemble d'objets Order. Un autre Type existe aussi, Mutation, contenant toutes les règles de mise à jour des données, comme les insertions par exemple. Les deux blocs suivants définissent les structures de objets Product et Order. Comme expliqué dans la section précédente, le client pourra demander tous les attributs de chaque type, ou moins.

À travers la déclaration du squelette de l'API, on comprend mieux l'appellation du langage : GraphQL. En effet, une réponse conforme au schéma de l'exemple peut être représentée par l'arbre ci-contre. Un premier niveau de l'arbre contient toutes les commandes (orders). À chaque branche order, on retrouve d'autres sous-divisions product, correspondant aux champs productsList. Dans une API REST, il aurait par exemple fallu demander la liste des commandes, puis pour chaque commande, demander les produits qui y appartiennent. Dans l'idée, la structure arborescente de GraphQL devient plus avantageuse quand l'arbre devient plus profond. Le langage a peu de limites puisqu'il est capable de prendre en charge des relations beaucoup plus complexes, avec des objets interdépendants par exemple.

Attention à la confusion : le nom de Graph Query Language ne vient pas du fait que GraphQL est destiné aux bases de données orientées graphes, mais bien de la structure arborescente des réponses aux requêtes. Il ne faut donc surtout pas confondre GraphQL avec GQL.

• Site officiel