À propos de ce cours
Objectif : comprendre ce que GraphQL change par rapport à REST et interroger une API GraphQL depuis Flutter.
Le problème que GraphQL résout
Imaginez l'écran de profil d'un réseau social : nom, photo, trois derniers posts et nombre d'amis. Avec REST, il faut souvent plusieurs requêtes (sous-chargement, under-fetching) et chacune renvoie des champs inutiles (sur-chargement, over-fetching), ce qui pèse sur le forfait mobile et la batterie.
Analogie : le menu fixe et le buffet
- REST = menu fixe: chaque plat (endpoint) arrive complet, avec ce que vous n'avez pas demandé.
- GraphQL = buffet à la carte: vous remplissez votre assiette avec exactement ce que vous voulez, en un seul passage.
Le vocabulaire GraphQL
| Terme | Rôle | Équivalent REST |
|---|---|---|
| Schema | Liste des types et champs disponibles (le « contrat ») | Documentation des endpoints |
| Query | Lire des données | GET |
| Mutation | Créer, modifier, supprimer | POST, PUT, DELETE |
| Subscription | Recevoir des mises à jour en temps réel | WebSocket |
| Variables | Paramètres d'une requête ($code) |
Paramètres d'URL |
Une requête GraphQL
On utilise l'API publique gratuite Countries (https://countries.trevorblades.com/), sans clé. Testez d'abord la requête dans son explorateur en ligne.
# Liste de tous les pays : on ne demande que 4 champs
query {
countries {
code
name
emoji
capital
}
}
# Un pays précis, avec une variable
query GetCountry($code: ID!) {
country(code: $code) {
name
capital
currency
languages { name }
continent { name }
}
}
Démystifier : GraphQL n'est qu'un POST
Avant d'installer un package, il faut comprendre qu'une requête GraphQL est un simple POST HTTP avec un corps JSON contenant query et variables:
Future<Map<String, dynamic>> fetchCountry(String code) async {
final response = await http.post(
Uri.parse('https://countries.trevorblades.com/'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({
'query': r'''
query GetCountry($code: ID!) {
country(code: $code) { name capital currency emoji }
}
''',
'variables': {'code': code},
}),
);
final json = jsonDecode(response.body);
if (json['errors'] != null) throw Exception(json['errors'][0]['message']);
return json['data']['country'];
}
Notez deux différences avec REST : la réponse est toujours dans data, et les erreurs arrivent souvent dans un tableau errors avec un code 200. Il faut donc vérifier errors, pas seulement le statut.
Avec le package graphql_flutter
Ce package apporte un cache, des widgets Query et Mutation, et la gestion de l'état de chargement.
flutter pub add graphql_flutter
import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';
const String countriesQuery = r'''
query {
countries { code name emoji capital }
}
''';
void main() async {
await initHiveForFlutter(); // cache persistant
final client = ValueNotifier(
GraphQLClient(
link: HttpLink('https://countries.trevorblades.com/'),
cache: GraphQLCache(store: HiveStore()),
),
);
runApp(GraphQLProvider(
client: client,
child: const MaterialApp(home: CountriesPage()),
));
}
class CountriesPage extends StatelessWidget {
const CountriesPage({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Pays du monde')),
body: Query(
options: QueryOptions(document: gql(countriesQuery)),
builder: (QueryResult result, {VoidCallback? refetch, FetchMore? fetchMore}) {
if (result.isLoading) {
return const Center(child: CircularProgressIndicator());
}
if (result.hasException) {
return Center(child: Text('Erreur : ${result.exception}'));
}
final countries = result.data?['countries'] as List<dynamic>? ?? [];
return ListView.builder(
itemCount: countries.length,
itemBuilder: (context, i) {
final c = countries[i];
return ListTile(
leading: Text(c['emoji'], style: const TextStyle(fontSize: 28)),
title: Text(c['name']),
subtitle: Text('Capitale : ${c['capital'] ?? '—'}'),
);
},
);
},
),
);
}
}
On retrouve les trois mêmes états que dans la leçon 24.5 : isLoading, hasException, data.
Une mutation
L'API Countries est en lecture seule. Pour vous entraîner aux mutations, utilisez une API comme GraphQLZero (fausse API GraphQL de type JSONPlaceholder) :
const String createPost = r'''
mutation CreatePost($input: CreatePostInput!) {
createPost(input: $input) { id title }
}
''';
final result = await GraphQLProvider.of(context).value.mutate(
MutationOptions(
document: gql(createPost),
variables: {'input': {'title': 'Mon premier post', 'body': 'Bonjour !'}},
),
);
if (!result.hasException) print('Créé : ${result.data?['createPost']}');
REST ou GraphQL : lequel choisir ?
| Critère | REST | GraphQL |
|---|---|---|
| Simplicité pour débuter | ⭐⭐⭐ | ⭐⭐ |
| Nombre d'endpoints | Un par ressource | Un seul |
| Données renvoyées | Fixées par le serveur | Choisies par le client |
| Écrans qui combinent beaucoup de données | Plusieurs requêtes | Une requête |
| Cache HTTP standard | Facile | Plus complexe |
| Usage typique | La majorité des API publiques | Applications riches (réseaux sociaux, e-commerce) |
En pratique, c'est le serveur qui décide: votre application Flutter doit savoir consommer les deux.
Activité 24.7 — « Atlas des pays » (1 h 15)
- Dans l'explorateur en ligne de l'API Countries, écrivez une requête qui renvoie les pays d'Afrique (filtre
countries(filter: { continent: { eq: "AF" } })) avec nom, drapeau et capitale. - Intégrez cette requête dans Flutter avec
graphql_flutter. - Au clic sur un pays, ouvrez une page de détail qui utilise la requête
GetCountryavec une variable ($code) et affiche monnaie, langues et continent. - Ajoutez des
ChoiceChippour changer de continent (AF, EU, AS, NA, SA, OC) : la variable change, la liste se met à jour. - Comparaison : combien de requêtes REST faudrait-il pour afficher la même page de détail si les langues et le continent étaient des endpoints séparés ?
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !