Développeur FullStack & Devops

GraphQL

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 toutes les différentes 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. 1 unique point d’entrée, 1 seule URL (contrairement aux API REST)
  3. possibilité pour les équipes Front End (aussi en charge du serveur GraphQL) de modifier rapidement les UI (et donc leurs besoins en données)
  4. lorsque plusieurs clients 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 (possibilité de mettre en cache en amont) en mixant et filtrant les données issues de différents endpoints
  5. Monitoring et infos Analytics possible (dans les resolvers)
  6. typage fort

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 : 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 : Schema Definition Language, est un langage de description des types disponibles dans un schéma et les relations entre ces types. Ce langage spécifique à GraphQL doit etre stocké sous forme de String (plus simple avec les templates littérals)

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

Resolvers : fonctions permettant d’interagir avec les données

Schema et Operations

Coté serveur GraphQL, un schema est formé d’une collection de types objet, ainsi que des types un peu particuliers, les root types:

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 concrets vont définir la structure des données et sont composés de pairs de clés/types primitifs ou  clés/types 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 de notre API, ils vont permettre aux clients GraphQL d’interagir avec le serveur GraphQL. Nous pouvons en utiliser un ou plusieurs dans notre 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)

 

rédigé par behrouze le 31/10/2018
Cheat SheetsOutilsVidéosA propos