Découvrir GraphQL: le "next-generation API" ? - Partie 1

Dans cet article, nous allons parler du phénomène GraphQL qui a eu beaucoup de succès lors de son avènement dans le monde du développement...

Découvrir GraphQL: le "next-generation API" ? - Partie 1

Dans cette première partie de l'aventure GraphQL, nous aborderons les quatre points suivants.

  1. Qu'est-ce que GraphQL
  2. Comment fonctionne GraphQL
  3. Qu'est-ce qui caractèrise GraphQL
  4. Comparaison avec REST

Ça sera une brève introduction pour comprendre les notions de bases du langage de requête GraphQL. Nous rappelons que ces notions restent non exhaustives et que nous voulons juste armer nos lecteurs pour qu'ils puissent entamer les projets GraphQL dans les articles à venir.

Qu'est-ce que GraphQL

Capture d’écran 2021-05-12 212032.jpg

GraphQL (Graph Query Language) est un langage de requêtes et un environnement d'exécution, créé par Facebook en 2012, avant d'être publié comme projet open-source en 2015. Inscrit dans le modèle Client-Serveur, il propose une alternative aux API REST. La requête du client définit une structure de données, dont le stockage est éventuellement distribué, et le serveur suit cette structure pour retourner la réponse. Fortement typé, ce langage évite les problèmes de retour de données insuffisants (under-fetching) ou surnuméraires (over-fetching). ( Wikipédia)

Au début, il a été développé spécifiquement pour les applications mobiles, depuis son utilisation s’est étendue à tous les types de développement comme alternative aux API REST. Il donne le pouvoir de définir et de structurer les données nécessaires, ce qui réduit considérablement le nombre d’appels d’API. En plus, il garantit la structuration des données renvoyées et s'assure de la contenance des informations demandées. Plus précisément GraphQL assure qu’une plateforme récupère exactement ce qui est nécessaire sur le serveur.

C'est est un langage de requête similaire à SQL, qui comprend à la fois un environnement d’exécution et un système de typage.

Comment fonctionne GraphQL

Pour comprendre le fonctionnement de GraphQL, il est important de connaitre le rôle de ses trois composantes principales à savoir :

  • langage de requête
  • système de typage
  • environnement d'exécution

Un langage de requête

L'essence première de GraphQL c'est d'être un langage de requête (Query Language) qui offre aux programmes un accès facile aux API. Ses requêtes se distinguent par un degré de flexibilité remarquable. Pas de restrictions dans le nombre de requêtes pouvant être formulées, et nous pouvons définir avec beaucoup de précision les champs de données que nous souhaitons interroger. GraphQL permet de faire à la fois des requêtes en lecture et en écriture.

  • Requête

    {
     orders {
         id
         productsList {
             product {
                 name
                 price
             }
             quantity
         }
         totalAmount
     }
    }
    
  • Réponse

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

Un système de typage

GraphQL fonctionne d’ailleurs avec son propre système de typage qui vous permet de décrire votre API au moyen de types de données. Les structures de données ainsi définies créent en fait le cadre dans lequel sont exécutées les requêtes. Chaque type est composé d’un ou de plusieurs champ(s) contenant à leur tour leurs propres types. Ce système spécifique ainsi mis en place constitue pour GraphQL un point de repère qui lui permet de valider les requêtes et de réfuter les requêtes contenant des erreurs.

Un environnement d’exécution

GraphQL offre aussi l’environnement d’exécution serveur qui permet d’exécuter les requêtes GraphQL. Pour ce faire, on dispose de bibliothèques destinées à divers langages de programmation. L’environnement d’exécution sert exclusivement à l’analyse syntaxique et à la validation des requêtes, ainsi qu’à la sérialisation des réponses. L’enregistrement et la communication des données sont assurés par votre application web.

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
}

En parfaite collaboration, le langage de requêtes, le système de typage et l’environnement d’exécution nous offrent un échafaudage API d’excellente qualité. Ces éléments sont non seulement compatibles avec toutes sortes de plateformes et d’utilisations, mais ils s’adaptent aussi parfaitement aux particularités de votre application Web : nous pouvons donc intégrer l’interface GraphQL dans le code de votre projet, quelque soit le Framework utilisé.

Qu'est-ce qui caractèrise GraphQL

  • L'une des principale caractéristique de GraphQL est la simplicité du langage de requête.
  • Le format des données de réponses est tout aussi simple que celui employé par le JSON (JavaScript Object Notation).
  • Sa structure hiérarchisée qui facilitent l’exécution (et la réponse) de requêtes complexes dans une seule et même requête.
  • Son typage fort qui fait que chaque couche d’une requête GraphQL correspond à un type bien précis, sachant que chaque type permet de décrire un ensemble de champs disponibles.
  • GraphQL vous permet de lancer des requêtes en toute flexibilité.
  • Il vous offre ainsi une très grande liberté et beaucoup de souplesse en termes de développement, voire d’adaptation de votre interface.

Comparaison avec REST

graphqlvsrest.png

Une API REST est une interface de programmation d'application qui respecte les contraintes du style d'architecture REST et permet d'interagir avec les services web RESTful. L'architecture REST (Representational State Transfer) a été créée par l'informaticien Roy Fielding.

Le GraphQL se résume par la mise à disposition d’une interface de requêtage qui s’appuie sur les mêmes technologies d’intégration utilisées par les API REST. Nous allons toujours passer par le protocole HTTP et par un payload de retour, préférablement au format JSON, mais la différence pour le client repose sur le contrat d’interface.

  • Dans une architecture REST, le couple requête/réponse est bien défini. Le client de l'API, ne peut pas avoir une structure de requête/réponse différente de celle définie par le créateur de l'API.
  • Dans une API GraphQL, le client défini avec précision la structure de la requête/réponse, et obtient donc, ni plus ni moins, les informations dont il a besoin sur les champs qu'il a visé.
  • GraphQL définie un contrat entre les acteurs, une interface déclarative décrivant ce qu'il est possible de requêter et dans quelle mesure, là où REST est plus abstrait bien que certains standards tel que JSON API ont essayés de standardiser un peu le concept.

Nous arrivons à la fin de ce premier article qui est le début d'une longue série consacrée au langage de requête GraphQL. Dans cet article, nous avons abordé les notions de base de GraphQL qui restent non exhaustives malgré le nombre de points touchés. Pour les articles à venir, nous allons entré dans le vif du sujet en parlant de schéma, typage, Query, Mutation, ...