Comment une appli météo trouve ses chiffres
Une API (Application Programming Interface) est une façon pour un programme d’en interroger un autre par le web. Elle répond avec des données et non avec une page.
Ton appli météo n’a pas de thermomètre : elle demande la température à une API. Tu vas apprendre à lire cette réponse et à en écrire une.
À la fin de cette leçon
Remarque
Je peux lire et envoyer des données au format JSON avec une API.
Mots clés
| Mot | Ce que ça veut dire | Exemple |
|---|---|---|
| API | un service web qu’un programme interroge pour obtenir ou envoyer des données | |
| JSON | un texte qui décrit des données avec des accolades et des crochets | {"nom": "pain"} |
| Clé | le nom d’une donnée dans un objet JSON | |
| GET | la méthode qui lit des données sans rien changer | |
| POST | la méthode qui envoie une nouvelle donnée au serveur | |
| Corps | les données qu’une requête POST transporte |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
JSON écrit des données en texte
Le JSON (JavaScript Object Notation) est le format que presque toutes les API utilisent. Un objet s’écrit entre accolades, avec des clés et des valeurs.
Les textes sont entre guillemets doubles. Les nombres n’en ont pas. Une liste s’écrit entre crochets, avec des virgules.
Exemple travaillé : lire un objet JSON
| Morceau de JSON | Ce que c’est | Valeur |
|---|---|---|
| "nom": "baguette" | Une clé et un texte | baguette |
| "prix_centimes": 130 | Une clé et un nombre | 130 |
| "en_stock": true | Une clé et un booléen | vrai |
| [{"nom": "pain"}, {"nom": "brioche"}] | Une liste de deux objets | 2 produits |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Demande à l’API si elle répond
curl -s -o /dev/null -w '%{http_code}\n' http://api:3000/Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Demande une ressource qui n’existe pas
curl -s -o /dev/null -w '%{http_code}\n' http://api:3000/rien_du_toutAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Ce que disent ces deux Runs
Le service api du lab donne un accès web aux tables de la base. Sa racine répond 200 : elle décrit ce qu’elle sait faire.
Une table qui n’existe pas donne 404. C’est le même code que pour une page absente : la ressource demandée n’est pas là.
GET lit, POST ajoute
Pour lire des données, un client envoie GET sur l’adresse d’une ressource. La réponse porte du JSON.
Pour en ajouter, il envoie POST avec un corps en JSON et l’en-tête Content-Type: application/json. Le serveur répond 201 quand la donnée est créée.
Exemple : lire puis ajouter un produit
# Exemple : une table produits qu'il faudrait créer d'abord.
curl http://api:3000/produits
# Réponse possible :
[{"id": 1, "nom": "baguette", "prix_centimes": 130, "stock": 14}]
# Ajouter un produit : le corps JSON décrit le nouveau produit.
curl -X POST http://api:3000/produits \
-H "Content-Type: application/json" \
-d '{"nom": "brioche", "prix_centimes": 250, "stock": 8}'
# Réponse attendue : le code 201, c'est-à-dire créé.Un prix se garde en centimes entiers
Dans l’exemple, le prix est 130, pas 1.30. Les nombres à virgule se trompent d’un tout petit peu : en Python, 0.1 + 0.2 ne donne pas exactement 0.3.
Pour de l’argent, on garde donc des centimes, en nombre entier. On ajoute la virgule seulement à l’affichage.
Exemple travaillé : le stock en centimes
| Produit | Prix en centimes | Stock | Valeur en centimes |
|---|---|---|---|
| baguette | 130 | 14 | 1820 |
| croissant | 110 | 0 | 0 |
| brioche | 250 | 8 | 2000 |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une erreur fréquente
Attention
Beaucoup pensent que JSON est du code Python. Ce n’est qu’un texte. Il faut le lire avec json.loads pour obtenir des listes et des dictionnaires. Et JSON écrit true et false en minuscules, pas True.
Pour aller plus loin : le plus cher
Ajoute le_plus_cher(texte), qui renvoie le nom du produit au plus grand prix. Garde le meilleur prix vu jusqu’ici dans une boucle.
Essaie-la avec un seul produit, puis avec une liste vide. Que doit-elle répondre dans ce dernier cas ?