Les API
Une API, pour application programming interface, est la liste de ce qu'un programme accepte qu'on lui demande. Une API web est un serveur dont les réponses sont faites pour être lues par un autre programme, et non par un humain.
Le problème
On veut un classement en ligne : à la fin d'une partie, le jeu envoie le résultat, et l'écran d'accueil affiche les dix meilleurs.
Le jeu et le serveur sont deux programmes séparés, peut-être sur deux machines. Ils doivent se mettre d'accord sur trois choses : quoi demander, sous quelle forme, et comment savoir si ça a marché. Cet accord, c'est l'API.
La notion
Une requête HTTP
HTTP est le langage du web. Une requête contient quatre éléments.
| Élément | Exemple | Rôle |
|---|---|---|
| Méthode | POST | L'intention |
| Chemin | /scores | La ressource visée |
| En-têtes | Content- | Des précisions sur la requête |
| Corps | {"player": | Les données envoyées, facultatif |
Les méthodes
| Méthode | Intention | Exemple |
|---|---|---|
GET | Lire, sans rien modifier | GET /scores |
POST | Créer | POST /scores |
PUT ou PATCH | Modifier | PATCH / |
DELETE | Supprimer | DELETE / |
Le chemin nomme une chose, au pluriel, et la méthode dit ce qu'on en fait. On écrit POST /scores, pas GET /.
La réponse et son code de statut
La réponse commence par un nombre à trois chiffres. Son premier chiffre dit l'essentiel.
| Famille | Sens | Les plus courants |
|---|---|---|
| 2xx | Réussi | 200 OK, 201 Created |
| 3xx | Aller voir ailleurs | 301 Moved Permanently |
| 4xx | Erreur du client : la requête est mauvaise | 400, 401, 404 Not Found, 422 |
| 5xx | Erreur du serveur : il a planté | 500 Internal Server Error |
Devant une erreur, ce chiffre dit de quel côté chercher : 4xx, on corrige la requête ; 5xx, on lit les journaux du serveur.
JSON
JSON est le format d'échange le plus répandu. Le projet l'utilise déjà pour ses sauvegardes.
JSON
| JSON | Python |
|---|---|
| Objet, entre accolades | dict |
| Tableau, entre crochets | list |
true, false, null | True, False, None |
| Chaîne, toujours entre guillemets doubles | str |
JSON n'a pas de tuple : un tuple Python envoyé en JSON revient sous forme de liste. C'est l'origine du bug des voisins après chargement, détaillé dans Choisir sa structure de données.
Concevoir avant de coder
On écrit d'abord le contrat. Pour le classement, deux routes suffisent.
| Méthode et chemin | Corps envoyé | Réponse |
|---|---|---|
GET /scores | Aucun | 200 et la liste des dix meilleurs |
POST /scores | Un joueur et un nombre de tours | 201 et le score enregistré |
Le score retenu ici est le nombre de tours pour gagner : moins il y en a, mieux c'est. Le jeu n'a pas encore de condition de victoire, voir l'état actuel (documentation du jeu) ; l'API peut être écrite et testée avant.
Écrire l'API avec FastAPI
FastAPI est une bibliothèque Python pour écrire des API. On crée un dossier server/ à la racine du projet, séparé du jeu.
Code
Code
Python
Ce qu'il faut y lire :
@app.relie une méthode et un chemin à une fonction Python.get("/ scores") - La classe
Scoredécrit le corps attendu. FastAPI vérifie chaque requête : si un champ manque ou n'a pas le bon type, il répond422sans appeler la fonction. - Ce que la fonction renvoie est converti en JSON.
On installe et on lance, dans un environnement virtuel propre au serveur :
Bash
uvicorn est le programme qui écoute sur le port, 8000 par défaut, et passe les requêtes à app. L'option --reload relance le serveur à chaque modification du fichier.
Essayer avec curl
Dans un deuxième terminal.
Bash
Code
Bash
Code
Et une requête incomplète :
Bash
JSON
Le code est 422 et le message dit quel champ manque. Une bonne API explique ses refus.
Appeler l'API depuis le jeu
Côté jeu, on utilise la bibliothèque requests, à ajouter au requirements. du jeu.
Python
Deux précautions, qui valent pour tout appel réseau :
timeout. Sans lui, un serveur qui ne répond pas fige le jeu indéfiniment.tryetexcept. Le réseau peut tomber à tout moment. Le jeu doit rester jouable sans classement.
Même avec un délai de trois secondes, l'appel bloque la boucle d'affichage pendant ce temps. Le faire en fin de partie ou à l'ouverture d'un menu, jamais à chaque image.
Les limites de cette version
| Limite | Conséquence | Piste |
|---|---|---|
| Les scores sont dans une liste en mémoire | Ils disparaissent à chaque redémarrage du serveur | Une base de données, voir Docker Compose |
| Aucune identification | N'importe qui peut envoyer n'importe quel score | Une clé d'API, puis de vrais comptes |
| Le client déclare son propre score | Tricher est trivial | Que le serveur rejoue ou valide la partie |
| HTTP en clair | Les échanges sont lisibles sur le réseau | HTTPS |
Aucune n'empêche d'apprendre. Toutes comptent le jour où l'API est ouverte sur Internet.
À retenir
- Une API est un contrat : méthode, chemin, forme des données, codes de statut.
GETlit,POSTcrée. Le chemin nomme une chose.- 2xx réussi, 4xx erreur du client, 5xx erreur du serveur.
- Côté client : toujours un délai maximal, toujours prévoir l'échec.
- On écrit le contrat avant le code.
Exercices
- Lancer l'API, ajouter trois scores avec
curl, vérifier que la liste revient triée. - Ouvrir
/docset envoyer un score depuis cette page. - Ajouter une route
GET /qui renvoie les scores d'un joueur, etscores/ {player} 404s'il n'en a aucun. - Refuser un nombre de tours négatif ou nul. Quel code de statut convient ?
- Arrêter le serveur et appeler
fetch_depuis un interpréteur Python. Que renvoie la fonction, en combien de temps ?scores() - Écrire le contrat, sans le coder, d'une API de sauvegardes en ligne : quelles routes, quels corps, quels codes ?