C'est quoi une API ? Enfin une explication claire (avec des brochettes)

C'est quoi une API ? Enfin une explication claire (avec des brochettes)

Une API, c'est un restaurant de brochettes : une feuille, des cases à remplir, un serveur, et des plats qui reviennent cuisinés. Requête, réponse, codes 200 et 404, clé d'API : l'essentiel en 5 minutes.

Ton téléphone n'a pas de satellite. Et pourtant, ton appli météo sait qu'il va pleuvoir demain.

Ton app de paiement n'a pas une banque cachée à l'intérieur. Et pourtant, le virement part.

Pourquoi ? Parce que ces apps demandent à quelqu'un d'autre de faire le travail. Et cette façon de demander, c'est exactement ce qu'on appelle une API.

Je crée des applications mobiles depuis 2008. Des API, j'en consomme tous les jours, et j'en ai créé des centaines. Dans cet article (et dans la vidéo juste en dessous), je t'explique ce que c'est, comment lire une requête, et je te montre un vrai appel en direct.

Une API, c'est quoi ?

Une API, c'est un ensemble de règles qui permettent à deux logiciels de se parler, sans que l'un ait besoin de savoir comment l'autre est fabriqué à l'intérieur.

Dit comme ça, c'est abstrait. Alors je vais prendre une image, et si tu es du sud, tu vas la reconnaître tout de suite.

Le restaurant de brochettes

Tu connais ces restaurants de brochettes où, quand tu t'installes, il y a déjà une feuille posée sur la table ?

Cette feuille, c'est un peu le menu. Elle liste tout ce que tu peux commander. Les brochettes : poulet, bœuf, saucisse, magret. Les accompagnements : frites, camembert, légumes. Sur chaque ligne, il y a le nom, le prix, et une case vide. Et il y a un crayon posé à côté.

Chacun autour de la table choisit ce qu'il veut, et tu écris juste le nombre dans la case. Deux bœuf, une poulet, trois frites, deux camembert. (Petit conseil au passage : le camembert, demande-le en début de repas pour tremper les frites dedans. Mais c'est un autre sujet.)

Tu rends la feuille au serveur. Et un peu plus tard, il revient avec les plats. Cuisinés.

Eh bien ça, c'est une API. Et cette feuille t'apprend tout ce qu'il faut savoir.

La feuille te dit ce que tu as le droit de demander

Tu ne peux pas écrire « sushi » dessus. Si ce n'est pas sur la feuille, ce n'est pas au menu.

Une API, c'est pareil : elle a une liste de choses qu'elle sait faire, et rien d'autre. Cette liste, en API Web, on l'appelle la documentation. Le plus souvent c'est un site web qui détaille toutes les possibilités de l'API et comment s'en servir (parfois un PDF).

Tu ne fais pas que cocher, tu écris des nombres

Tu précises combien de brochettes tu veux pour chaque type. Ça, ce sont les paramètres : tu affines ta demande.

Tu ne vas jamais en cuisine

Tu ne sais pas quel four ils utilisent, quelle est leur recette, ni combien ils sont derrière. Et franchement, tant mieux. S'ils changent tout leur matériel demain, ta feuille, elle, ne change pas. Tu commandes exactement pareil.

Avec une API, c'est la même chose. Quand tu lui demandes un résultat, tu n'as pas besoin de savoir comment elle s'y prend. Tu ne sais même pas dans quel langage elle a été programmée.

Donc pour résumer l'image :

  • la feuille, c'est ce que tu as le droit de demander ;
  • le serveur, c'est le transport ;
  • les plats cuisinés, c'est la réponse, prête à être utilisée.

API web ou API logicielle ?

Petite précision avant d'aller plus loin. Le mot API s'utilise dans deux contextes : les API web, et les API logicielles (quand plusieurs bibliothèques de code communiquent entre elles).

Mais quand tu débutes et que tu tapes « API » dans une barre de recherche, dans 9 cas sur 10 tu parles d'une API web. C'est celle-là qu'on regarde ici.

On pourrait aller très loin (REST, GraphQL, créer sa propre API…). Aujourd'hui on se concentre sur l'essentiel : utiliser une API qui existe déjà.

Ce qu'il y a dans une requête

Une requête, c'est ta feuille remplie. Il y a trois choses essentielles dedans.

1. L'adresse. C'est l'URL, on parle aussi d'endpoint (les développeurs aiment bien parler anglais). C'est là où tu frappes.

2. La méthode. Quatre verbes suffisent :

  • GET : je lis
  • POST : je crée
  • PUT : je modifie
  • DELETE : je supprime

3. Les paramètres. Ce sont les nombres que tu écris en face des lignes. On les met soit dans l'adresse, soit dans le corps de la requête, pour préciser à l'API ce que tu veux recevoir exactement.

Ce qu'il y a dans une réponse

Une fois la requête envoyée, l'API te répond. Et dans cette réponse, il y a deux choses à lire.

Le statut. C'est un nombre compris entre 100 et 599. Quatre valeurs reviennent tout le temps :

  • 200 : ça a marché, la réponse correspond à ce que tu as demandé
  • 404 : ça n'existe pas
  • 401 : tu n'as pas le droit
  • 500 : c'est cassé chez eux (et là, ce n'est pas ta faute, tu peux respirer)

Les données, qu'on appelle aussi le corps de la réponse. Au restaurant, ce sont les plats. En programmation, dans l'immense majorité des cas, c'est du JSON.

Si le mot JSON ne te dit rien, j'ai une vidéo de 5 minutes là-dessus, et les deux vont très bien ensemble : JSON : enfin une explication claire (en 5 min).

Ton premier appel d'API, sans rien installer

Tu peux tester tout de suite, avec ton navigateur. Pas d'outil compliqué.

Ouvre cette adresse : https://jsonplaceholder.typicode.com/users/1

Voilà. Tu viens de faire un appel d'API. Ton navigateur a envoyé un GET à cette adresse, le serveur a répondu, et ce que tu vois à l'écran, c'est du JSON.

Pour voir le détail de l'échange, ouvre l'inspecteur de ton navigateur (onglet Réseau) et recharge la page. Tu retrouves tout ce dont on vient de parler : la méthode GET, le code 200, et les données. (Attention, ici « serveur » veut dire un ordinateur toujours allumé et connecté à Internet. Rien à voir avec le serveur du restaurant.)

Maintenant, remplace le 1 par 999 : https://jsonplaceholder.typicode.com/users/999

Hop, 404. L'utilisateur 999 n'existe pas. C'est exactement comme si tu écrivais « sushi » sur la feuille : le serveur revient et te dit « désolé, on n'en fait pas ».

(Personnellement, si un serveur de restaurant me répondait « 404 » quand je demande un plat qui n'est plus au menu, je serais fan.)

Mais en tant que développeur, retiens bien ça : ton app va planter ici si tu ne gères pas ce cas. C'est une erreur très courante. À toi de prévoir ce que tu affiches quand une API te renvoie autre chose que 200.

Et en code, ça donne quoi ?

Voici le même appel dans une app Flutter, en Dart :

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> chargerUtilisateur() async {
  final reponse = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/users/1'),
  );

  if (reponse.statusCode == 200) {
    final utilisateur = jsonDecode(reponse.body);
    print(utilisateur['name']);
  } else {
    print('Erreur : ${reponse.statusCode}');
  }
}

Remarque le if sur le statusCode : c'est la gestion du 404 dont je te parlais juste au-dessus.

Et ce code serait quasiment le même en JavaScript, en PHP, en Swift ou dans n'importe quel autre langage. Une fois que tu as compris le principe de la requête et de la réponse, tu sais le faire partout. Tu changes juste la syntaxe.

Un point avancé, mais important : la clé d'API

Normalement c'est un sujet un peu plus avancé. Mais ça me paraît dangereux de ne pas t'en parler si tu débutes.

L'API qu'on vient d'utiliser est une API de démo. La plupart des vraies API (météo, paiement, IA…) vont te demander une clé d'authentification. Elles ont besoin de savoir qui tu es.

Pourquoi ? Parce que ce sont tes utilisateurs qui vont faire appel à ces API. Peut-être des milliers. Il y a souvent un quota gratuit au départ, mais si des dizaines de milliers de personnes interrogent l'API en permanence, quelqu'un va devoir payer. La clé, c'est ce qui permet à l'API de savoir à qui envoyer la facture à la fin du mois.

Donc cette clé, on ne la met jamais dans du code qu'on publie. On la stocke côté serveur. On peut aussi la restreindre à certains domaines ou à certaines applications. Il existe plein de moyens d'éviter que quelqu'un récupère ta clé et utilise l'API à ta place… avec ta carte bancaire.

C'est un sujet à part entière. Je voulais juste que tu le saches dès maintenant.

Ce qu'il faut retenir

Au restaurant : tu lis la feuille, tu écris ce que tu veux, le serveur te ramène les plats.

En code : une adresse, une méthode, des paramètres. Ça part vers un serveur, qui te renvoie un code et des données en JSON.

Voilà, c'est quasiment tout ce qu'il y a à savoir. Oui, on peut aller beaucoup plus loin. Mais dans 99 % des cas, si tu as compris ce principe-là, tu es prêt.

Passer de « je comprends » à « je l'utilise »

Si maintenant tu veux utiliser une API dans une vraie application, j'ai un parcours complet qui part vraiment de zéro pour créer ta première app avec Flutter et l'IA.

Le premier cours de ce parcours est entièrement gratuit. Tu y codes une application complète avec l'IA, en comprenant tout ce qu'elle produit. Et l'avantage, c'est que tu n'es pas dépendant d'un site no-code qui garde ton app prisonnière de sa plateforme : le code source est à toi.

Aucun piège, il est vraiment gratuit.

👉 Créer ta première app Flutter avec l'IA (gratuit)

Et si tu veux aller jusqu'au bout du sujet, le cours complet est là :

👉 Le cours complet Créer une app avec Flutter et l'IA

Il y a aussi tout le reste : le catalogue de cours et surtout la communauté, pour le jour où ton premier appel d'API te renverra un code que tu ne comprends pas.

👉 Les formules et la communauté Purple Giraffe

Et dis-moi en commentaire de la vidéo : est-ce que les API sont plus claires maintenant ? Et tu sais déjà laquelle tu veux utiliser en premier ?

Maxime

Happy coding.