GraphQL est une nouvelle norme d’API, qui fourni une alternative plus efficace, puissance et flexible à REST développé à l’origine par Facebook, pour répondre à un besoin de transfert de données adaptés aux nouveaux usages du web (mobile avec des taux de transfert restreint et qualité de connexion pas toujours au top).

Pour schématiser, GraphQL est composé d’un client et d’un serveur (l’API). C’est une sorte de concentrateur qui va jouer le rôle de point d’entrée unique des requêtes clientes qui va faire le lien avec des sources de données coté Back (API REST, bases de données, fichiers etc).

Caractéristiques principales

1. les clients récupèrent les données de manières déclarative, en spécifiant ce dont ils ont précisément besoin
2. un unique point d’entrée, 1 seule URL (contrairement aux API REST)
3. possibilité pour les équipes Front End (parfois aussi en charge du serveur GraphQL) de modifier rapidement les UI (et donc leurs besoins en données) sans attendre que l’équipe Back modifie les API
4. lorsque plusieurs type de clients (web, mobile etc.) ont besoin d’accéder aux mêmes sources de données, avec chacun des besoins particuliers en API, l’architecture REST oblige la modification des endpoints directement, alors qu’avec GraphQL, le serveur GraphQL va filtrer et renvoyer juste les données nécessaire en mixant et filtrant les données issues de différents endpoints
5. possibilité de mettre du cache
6. monitoring et infos Analytics possible (dans les resolvers)
7. typage fort contrairement à l’interrogation d’API qui retourne des données non typées

Outils

Apollo est un ensemble d’outils et de bibliothèques, créés selon les specs GraphQL, permettant de mettre en place rapidement un serveur GraphQL.

Concepts

Schema

un schéma est un contrat (ou interface) entre le client et le serveur GraphQL, c’est la description de l’ensemble des types simples ainsi que des fonctionnalités (types d’opérations/requêtes) disponibles sur le serveur graphQL. Il est défini à travers une chaine de caractère passé en paramètre de la méthode buildSchema( ) écrite en langage SDL .

SDL

SDL est l’acronyme de Schema Definition Language, c’est un langage de description des types disponibles dans un schéma et les relations entre ces types.
Ce langage spécifique à GraphQL doit être stocké sous forme de String (plus simple avec les templates littérals).

Resolvers

les resolvers sont le coeur de GraphQL, ce sont des fonctions coté serveur GraphQL, qui permettent d’interagir avec la couche de données (API, fichiers, bases de données etc).

Schema et Operations

Les opérations disponibles sont de 3 types :

• query : lecture de données
• mutation : création, modification ou suppression de données
• subscription : souscription à des éventements temps réel

Types

Le schéma coté serveur GraphQL, est formé d’une collection de types objet, ainsi que des root types (types un peu particuliers).

schema = types racine (query, mutations) + types objet

Types simple ou primitifs (scalar types)

• Int: entier 32‐bit signé
• Float: float à double-precision
• String: séquence de caractères UTF‐8
• Boolean: true ou false
• ID (serialisé en tant que String)

Types objet ou concrets (object types)

Les types objets ou types concret vont définir la structure des données et sont composés de pairs « clé:types primitifs » ou « clé:objet« .Ici le type Person est constitué des champs name, age et posts :

type Person { name: String! age: Int! posts: [Post!]! }

L’ensemble des types objets d’un schéma constitue le Modèle.

Types racine (root level types)

3 types spéciaux existent par convention, ce sont les types:
Query, Mutations et Subscription

Ce sont eux qui vont définir les points d’entrées, ils vont permettre aux clients GraphQL d’interagir avec le serveur GraphQL. Nous pouvons utiliser un ou plusieurs d’entre eux dans un schéma :

type Query { ... } type Mutation { ... } type Subscription { ... }

Chacun de ces 3 root types va définir les root field de l’API, qui sont les points d’entrées des requêtes clientes

type Query { allPersons(last: Int): [Person!]! }

Modificateurs de types : lists et non null

Les champs obligatoires sont marqué avec le « ! »

Les tableaux sont comme en Javascript représentés par des [ ]

Enumérations (Enumeration types)

Permet comme les enums de C# de définir un type qui est restreint à un ensemble défini de valeurs:

enum Message { MAIL SMS PHONE }

Types interfaces

Une interface est un contrat ou abstraction qui peut être implémenté par un type, on la définie avec le mot clé interface :

interface Message { id: ID! titre: String! message: String! destinataires: [Contacts]! }

et nos types peuvent l’implémenter en spécifiant le mot clé implements devant le nom de notre type Objet :

type Email implements Message { id: ID! titre : String! message: String! destinataires: [Contacts]! cc: [Contacts] cci: [Contacts] }

Opération coté client

Une opération exécutée coté client de type query pourrait ressembler à :

query { allPersons(last: 2) { name } }

On va ici interroger le serveur GraphQL, pour exécuter la Query allPersons en passant le paramètre optionnel last, pour récupérer les champs names uniquement.

Liens

HowToGraphQL.com Tuto vidéos gratuits de référence Fullstack GraphQL et blog (avec exemples d’implémentations)

Features d’Apollo V2 (19/07/18) et tuto officiel Apollo 2 et leur nombreux articles sur leur blog :

1. GraphQL explained
2. How to build a GraphQL server
3. Apollo Client: GraphQL with React and Redux
4. What’s Next.js for Apollo

Repo Github Apollo server 2 pour Express

Conferences dediés à GraphQL GraphQL Summit ou GraphQL Europe

GraphQL Radio podcast et la newsletter GraphQL Weekly

Prisma (ORM) GraphQL Server Basics | Part I: GraphQL Schemas, TypeDefs & Resolvers Explained | Part II: The Network Layer | Part III: Demystifying the info argument in GraphQL resolvers

React/Apollo client implémentation (dans un CodeSandbox)