Cette Refcard est un condensé de bonnes pratiques qui s'adresse autant aux consommateurs qu'aux développeurs d'API GraphQL. Elle aborde notamment la documentation, le versioning, le code first, le monitoring, la découvrabilité, la sécurité et le design de schéma.

1. There
is
a
better
way
octo.com
Quick Reference Card

2. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
Qu’est-ce que GraphQL ?
Créé par Facebook en 2012, GraphQLest à la fois un langage de requêtes pour lesAPI et un environnement permettant d'exécuter ces requêtes.
À l’époque, l’application mobile de Facebook rencontrait des problèmes de performance à cause du nombre important de requêtes qu’il
fallait pour charger le contenu de son fil d’actualité avec des API REST.
Son objectif principal est donc de permettre au consommateur de l’API de récupérer exactement les données dont il a besoin en une seule requête.
En 2015, GraphQL est devenu open-source et a depuis été adopté par plusieurs grandes entreprises telles que Github, Shopify, Twitter,
Coursera, Yelp, Netflix, Airbnb, Paypal et Contentful. Par la suite, sa part de marché n'a cessé de croître.
Depuis, certains leaders technologiques ont mis en place la GraphQL Foundation pour encourager le développement commun et l'évolution
de GraphQL.
GraphQL étant une spécification, plusieurs implémentations ont vu le jour, telles qu’Apollo, Graphene, ou encore Domain Graph Service.
Quand dois-je l’utiliser ?
Exemple de cas d’utilisation :
• Je suis une très grosse entreprise qui a des problématiques de performances réseau et charger une page signifie faire X appels (ex :
Facebook) ;
• Mon API est publique et je ne connais pas les cas d’usage de mes utilisateurs à l’avance (ex : Github, Shopify ou Contentful).
Utilisation déconseillée lorsque :
• Je n’ai pas beaucoup de consommateurs de mon API ;
• Je suis le seul utilisateur de mon API ;
• Mon API expose majoritairement des données statiques ;
• Personne ne sait faire du GraphQL dans l’équipe et nous devons livrer rapidement ;
• J'ai envie de créer un projet complexe en mettant un générateur GraphQL devant une base de données ;
• Mon API expose des données simples et indépendantes.
Les problèmes principaux résolus par GraphQL sont l'over-fetching, c'est-à-dire le fait de récupérer un nombre de données trop important
par rapport aux données dont nous avons vraiment besoin, et l'under-fetching.

3. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
query {
planet(id: 1) {
characters {
name
saberColor
}
}
}
POST /graphql
planet: {
characters: [
{
name: Darth Vader,
saberColor: red
},
{...}
]}
Ici,jesuisobligédefairen+1
appels afin d’accéder aux
ressources que je souhaite.
[
{id: 1, name: Luke Skywalker},
{id: 2, name: Darth Vader},
…
]
{ saberColor: red }
GET /planets/1/characters
GET /characters/n/sabers
API Rest
API GraphQL
?
Under-fetching
L’under-fetching est la nécessité de devoir faire plusieurs appels pour récupérer un ensemble de données cohérent d’un point de
vue fonctionnel.
J’ai besoin de la
couleur du sabre des
personnages venant
de la planète Tatooine.

4. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
Que renvoie une API GraphQL ?
GraphQL permet aux consommateurs de sélectionnerlesinformations qu'ils souhaitent recevoir de l'API. Pour cela, il leur suffit de préciser
les champs désirés dans leur requête.
Les erreurs métier, équivalentes aux codes d'erreur 4XX en REST, font partie intégrante du schéma (ou contrat d'interface) de l'API et
peuvent être filtrées de la même manière que les données.
Quant aux erreurs serveur, équivalentes aux codes d'erreur 5XX, elles sont listées dans le champ errors de la réponse.
Je souhaite récupérer le nom, l’espèce et
la planète du personnage dont l’id est 15.
Si le personnage n’est pas trouvé, je
souhaite récupérer un message d’erreur.
En général, les API GraphQL communicant via HTTP retournent un code
200, même en cas d’erreur.
query {
character(id: 15) {
__typename
... on Character {
name
species
planet
}
... on CharacterNotFound {
message
}
}
Requête
__typename est un champ qui
précise le type de l’objet, disponible
dans toutes les APIs GraphQL.

5. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
{
errors: [
{
message: Internal Server Error,
locations: [ {line: 2, column: 2} ],
path: [ character ],
extensions: {
code: NOT_IMPLEMENTED
}
}
],
data: {
character: null
}
}
Erreur serveur
{
data: {
character: {
__typename: Character,
name: Jar Jar Binks ,
species: Gungan,
planet: Naboo
}
}
}
Succès
{
data: {
character: {
__typename: CharacterNotFound,
message: Character not found
}
}
}
Erreur métier
Les champs
en erreur
doivent être
null
Réponses
Status Code : 200
TOUT VA BIEN.

6. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
Les bonnes pratiques.
Sécurité
Le standard pour gérer les autorisations est OAuth 2.
Il est vivement conseillé d’utiliser HTTPS pour toutes vos requêtes API/OAuth2.
Pour l’identification, le standard est OpenID Connect.
Il est recommandé de limiter la profondeur et le nombre d’opérations par requête,
ainsi que de mettre du rate limiting basé sur l’analyse de coût de chaque requête.
Code First
Il est préférable de décrire le schéma via du code puis de le générer plutôt que
d’écrire le schéma directement dans un .gql.
Cela permet de profiter d’un typage intelligent dans l’IDE et, ainsi, de limiter les
erreurs.
Documentation
Les commentaires du schéma doivent décrire les entités, de manière concise
et précise. Par exemple, ce que représente un type du schéma et ce que change
une mutation. Ajouter des exemples dans celle-ci réduit le TTFAC¹.
Cependant, elle doit être un complément au schéma et ne doit pas remplacer un
nommage explicite.
La meilleure documentation reste le code.
GraphiQL permet de générer une documentation interactive.
Il est conçu par la GraphQL Foundation et est très utilisé par la communauté.
Une alternative non interactive est GraphDoc.
Monitoring
Pour répondre au mieux à vos utilisateurs, il est indispensable de monitorer votre
API GraphQL.
On peut connaître les requêtes les plus utilisées et ainsi prioriser les améliorations de
DX² ou de performance.
Pour suivre une requête de bout en bout, il est conseillé d’utiliser un ID de corrélation.
Glossaire
¹ Time To First API Call : le temps que met un développeur entre l’ouverture de la documentation et son premier
appel à l’API.
² Developer Experience : qualité de l’expérience du développeur lorsqu’il interagit avec l’API.
³ Persisted Query : requête enregistrée lorsque le client l’envoie au serveur, puis accessible via un hash.
Cache
L’idéal pour le cache côté client ou serveur est d’utiliser des persisted queries³.
Côté client, les clefs de cache doivent contenir a minima le hash de la query et le
hash des variables. Pour les ressources privées, ces clefs doivent aussi contenir l’id
de l’utilisateur.
Aussi, une requête doit être mise en cache seulement si tous ses objets sont cachables.
Versioning
Le must est de faire évoluer l’API sans la versionner en limitant les breaking changes
ou en dépréciant les champs le cas échéant.
Lors d’un changement du contrat d’interface, il est impératif de communiquer les
champs dépréciés et la date de leur suppression. Ensuite, monitorer les champs
dépréciés pour avertir les consommateurs en retard.
Découvrabilité
Pour une API privée, il est vivement conseillé de bloquer l’introspection en prod et
de whitelister certains champs si besoin. Pour une sécurité accrue, l’utilisation de
persisted queries³ est conseillée.
Pour une API ouverte, il vaut mieux laisser l’introspection pour améliorer l’expérience
utilisateur. On peut cacher certains champs si nécessaire.

7. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
Requêtes avancées.
Les variables sont envoyées à côté de la
chaîne de caractères de la requête au serveur
GraphQL.
Cela améliore la réutilisabilité de la requête
(la chaîne de caractères de la requête reste
la même, seule la variable change) et
la sécurité (le type de la variable peut-être
imposé).
query Fetch(
$filter_luke: CharacterFilter!,
$filter_r2d2: CharacterFilter!
) {
luke: character(filter: $filter_luke) {
…Colors
},
r2-d2: character(filter: $filter_r2d2) {
…Colors
}
}
fragment Colors on Character {
hair_color
eye_color
}
{
filter_luke: {
name: Luke Skywalker
},
filter_r2d2: {
name: R2-D2
}
}
Les alias permettent au client de définir
le nom de retour d’un champ.
Les alias sont utiles quand le même champ
est requêté plusieurs fois (comme ici avec
le champ character).
Les fragments sont des groupes de champs
réutilisables. Ils sont utiles pour récupérer
plusieurs fois les mêmes champs dans
une requête.

8. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
query {
profile(id: 15) {
name
picture
}
actualities(id: 15) {
title
content
}
suggestions(id: 15) {
name
picture
}
}
Série ou parallèle ?
Les queries sont exécutées
en parallèle alors que les
mutations sont exécutées
en série, dans l’ordre de la
requête.
Je souhaite récupérer toutes
les informations de ma page
en une seule requête.

9. octo.com
Pagination.
La pagination divise un grand nombre de résultats en pages de taille limitée, par souci de performance.
Offset Pagination
La liste est découpée en pages qui contiennent chacune un nombre d’éléments.
Les autres paginations
La pagination par offset n’est plus pertinente si les données de votre API sont susceptibles d’évoluer entre deux appels. Dans ce cas, Il existe également
la pagination par curseur qui permet de requêter les objets après une certaine heure ou après un certain ID. Le framework Relay pousse la Relay
Connection Pagination, qui facilite son utilisation par le front. Cette pagination est plus compliquée à mettre en œuvre côté Backend.
Cette approche est souvent associée à des problèmes de performance
côté serveur et peut causer des problèmes de cohérence des données.
Néanmoins, elle reste la plus simple et la plus utilisée.
Je récupère beaucoup trop de résultats à chaque appel.
J’ai besoin de pagination pour en récupérer moins.
Maintenant je requête les Sith par lot de 10, à partir de la page 8.
Pour requêter les 10 prochains seigneurs Sith, je devrai faire la requête
sithLords(limit: 10, page: 9).
Requête
Réponse
query {
sithLords(limit: 10, page: 8) {
nodes {
id
name
}
pageInfo {
hasNextPage
totalPages
}
}
}
sithLords: {
nodes: [
{id: 71, name: Dark Vador},
…,
{id: 80, name: Dark Maul}
],
pageInfo: {
hasNextPage: true,
totalPages: 12
}
}

10. octo.com
Filtre.
Tri.
Un filtre permet d’affiner les résultats d’une recherche via des critères précis.
Pour ordonner les résultats d’une réponse, certaines APIs GraphQL
proposent un argument orderBy dans leurs requêtes.
Je veux récupérer les personnages
ayant un sabre vert.
Je veux récupérer une liste
des maîtres Jedi du plus petit
au plus grand.
Requête
query {
filterCharacterBySaberColor(
saberColor: green
) {
name
saberColor
}
}
Requête
query {
jediMasters(orderBy: {height: asc}) {
name
height
lightSaberColor
}
}
Les logiques de pagination, de filtre et de tri ne sont pas
natives à GraphQL. Elles sont à développer côté back-end.

11. octo.com
GRAPH
Q
LO
CTO
TECHNOLO
GY
Design du schéma.
Il existe trois Schémas Roots : les Query, les Mutations
et les Subscriptions dans lesquelles sont rangées les opérations.
Une Mutation est utilisée pour créer/modifier/
supprimer des entités.
type Query {
planet(id: ID!): PlanetReturn
}
type Mutation {
destroyPlanet(planetId: ID!): DestroyPlanetReturn
}
type Subscription {
planetDestroyed: Planet!
}
union PlanetReturn = Planet | PlanetNotFound | Error
union DestroyPlanetReturn = DestroyPlanetSuccess | PlanetNotFound |
PlanetAlreadyDestroyedError | Error
type Planet {
id: ID!
name: String!
destroyed: Boolean!
}
type DestroyPlanetSuccess {
id: ID!
name: String! @deprecated(
reason: Replaced by planetName. Removal on 2023-01-01.)
planetName: String!
}
interface Error {
message: String!
code: String!
path: [String!]!
}
type PlanetNotFoundError implements Error {
message: String!
code: String!
path: [String!]!
planetId: ID!
}
Returned type when the planet is already destroyed
type PlanetAlreadyDestroyedError implements Error {
message: String!
code: String!
path: [String!]!
planet: Planet!
}
Une Query est utilisée pour récupérer
des valeurs.
Il est obligatoire de définir une Query
Root dans un schéma GraphQL.
Une Subscription permet au serveur
GraphQL d’envoyer des données
à l’utilisateur lorsqu’un événement
se produit. Une connexion est donc
maintenue avec le client.
Il est possible d’utiliser du Server-sent
event ou du WebSocket.
Une union est un ensemble de types
concrets utilisé pour les types de retour.
Ce champ ne peut pas être null car il se
termine par un point d’exclamation.
Un Type représente une entité composée
de plusieurs propriétés.
Ici, une planète a un id, un nom et un état
détruit qui peut être vrai ou faux.
Une directive (précédée par un @)
permet d’ajouter de la logique technique
au schéma.
La plus connue est @deprecated qui permet
de préciser qu’un champ est déprécié.
Faire implémenter à vos erreurs métier
la même interface permet d’ajouter
de nouveaux cas d’erreurs sans provoquer
de breaking change.
Commentaire qui apparaîtra dans la
documentation (GraphiQL, GraphDoc…).

12. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
Bonnes pratiques de design.
Éviter les champs nullables
Par défaut, il est préférable de définir des
arguments et des champs non-nullables
(signalés par un point d’exclamation)
pour éviter aux clients de devoir coder
défensivement.
Exceptions :
- Ajout d’un champ à un type ou à une
opération (pour éviter un breaking change) ;
- Champs dépendant d’une source
susceptible d’échouer (appel réseau) pour
éviter les échecs en cascade.
Pas de verbe dans les Query (contrairement
aux mutations)
Repeat yourself
Trop réutiliser le même type peut mener à des incohérences
et rendre votre API moins évoluable. Dans le doute, mieux
vaut se répéter.
type Spaceship {
pilot: SpacePilot!
}
type Raceship {
pilot: RacePilot!
}
destroyPlanet(planetId: ID!) : DestroyPlanetReturn
planet(id: ID!)
destroyPlanetById(id: ID!)
destroyPlanetByName(name: String!)
destroyPlanet(planetId: ID!) : Planet
fetchPlanet(id: ID!)
getPlanet(id: ID!)
destroyPlanet(id: ID, name: String)
type Spaceship {
pilot: Pilot!
}
type RaceShip {
pilot: Pilot!
}
Éviter les opérations fourre-tout

13. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
OCTO Technology
“ Dans un monde complexe aux ressources finies, nous recherchons ensemble de meilleures
façons d'agir. Nous œuvrons à concevoir et à réaliser les produits numériques essentiels au
progrès de nos clients et à l'émergence d'écosystèmes vertueux”
– Manifeste OCTO Technology -
CABINET DE CONSEIL ET DE RÉALISATION IT
Paris
Toulouse
Hauts-de-France
IMPLANTATIONS
1OOO
OCTOS
OCTO EN TÊTE
DU PALMARÈS
3 CONFÉRENCES
FORMATION
La conférence tech par OCTO
3
6x

14. octo.com
GRAPH
Q
LO
CTO
TECHNO
LO
GY
© OCTO Technology 2023
Les informations contenues dans ce document présentent le point de vue
actuel d'OCTO Technology sur les sujets évoqués, à la date de publication.
Tout extrait ou diffusion partielle est interdit sans l'autorisation préalable
d'OCTO Technology.
Les noms de produits ou de sociétés cités dans ce document peuvent être
les marques déposées par leurs propriétaires respectifs.
Conçu, réalisé et édité par OCTO Technology.
Powered with by Maxime Bienassis
Antoine Mazure, Bastien Mourrat, Charlotte Petitbon Camille Vermorel