Aller au contenu

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émentExempleRôle
MéthodePOSTL'intention
Chemin/scoresLa ressource visée
En-têtesContent-Type: application/jsonDes précisions sur la requête
Corps{"player": "Alice", "turns": 42}Les données envoyées, facultatif

Les méthodes

MéthodeIntentionExemple
GETLire, sans rien modifierGET /scores
POSTCréerPOST /scores
PUT ou PATCHModifierPATCH /scores/12
DELETESupprimerDELETE /scores/12

Le chemin nomme une chose, au pluriel, et la méthode dit ce qu'on en fait. On écrit POST /scores, pas GET /ajouter_score.

La réponse et son code de statut

La réponse commence par un nombre à trois chiffres. Son premier chiffre dit l'essentiel.

FamilleSensLes plus courants
2xxRéussi200 OK, 201 Created
3xxAller voir ailleurs301 Moved Permanently
4xxErreur du client : la requête est mauvaise400, 401, 404 Not Found, 422
5xxErreur 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.

JSONJSON
{ "player": "Alice", "turns": 42, "won": true, "cities": ["Lyon", "Brest"] }
JSONPython
Objet, entre accoladesdict
Tableau, entre crochetslist
true, false, nullTrue, False, None
Chaîne, toujours entre guillemets doublesstr

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 cheminCorps envoyéRéponse
GET /scoresAucun200 et la liste des dix meilleurs
POST /scoresUn joueur et un nombre de tours201 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
server/ ├── main.py └── requirements.txt
Code
fastapi==0.115.6 uvicorn==0.34.0
Python
# server/main.py from fastapi import FastAPI from pydantic import BaseModel app = FastAPI(title="Scores BestGameOfTheYear") scores = [] class Score(BaseModel): player: str turns: int @app.get("/scores") def list_scores(): return sorted(scores, key=lambda s: s["turns"])[:10] @app.post("/scores", status_code=201) def add_score(score: Score): entry = {"player": score.player, "turns": score.turns} scores.append(entry) return entry

Ce qu'il faut y lire :

  • @app.get("/scores") relie une méthode et un chemin à une fonction Python.
  • La classe Score décrit le corps attendu. FastAPI vérifie chaque requête : si un champ manque ou n'a pas le bon type, il répond 422 sans appeler la fonction.
  • Ce que la fonction renvoie est converti en JSON.

On installe et on lance, dans un environnement virtuel propre au serveur :

TerminalBash
cd server python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt uvicorn main:app --reload

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.

TerminalBash
curl -i http://localhost:8000/scores
Code
HTTP/1.1 200 OK content-type: application/json []
TerminalBash
curl -i -X POST http://localhost:8000/scores \ -H "Content-Type: application/json" \ -d '{"player": "Alice", "turns": 42}'
Code
HTTP/1.1 201 Created content-type: application/json {"player":"Alice","turns":42}

Et une requête incomplète :

TerminalBash
curl -X POST http://localhost:8000/scores \ -H "Content-Type: application/json" \ -d '{"player": "Bob"}'
JSONJSON
{"detail":[{"type":"missing","loc":["body","turns"],"msg":"Field required","input":{"player":"Bob"}}]}

Le code est 422 et le message dit quel champ manque. Une bonne API explique ses refus.

La documentation est fournie

FastAPI génère une page qui liste les routes et permet de les essayer : http://localhost:8000/docs.

Appeler l'API depuis le jeu

Côté jeu, on utilise la bibliothèque requests, à ajouter au requirements.txt du jeu.

Python
# src/scores_client.py import requests API_URL = "http://localhost:8000" def send_score(player, turns): try: response = requests.post( f"{API_URL}/scores", json={"player": player, "turns": turns}, timeout=3, ) return response.status_code == 201 except requests.RequestException: return False def fetch_scores(): try: response = requests.get(f"{API_URL}/scores", timeout=3) response.raise_for_status() return response.json() except requests.RequestException: return []

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.
  • try et except. 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

LimiteConséquencePiste
Les scores sont dans une liste en mémoireIls disparaissent à chaque redémarrage du serveurUne base de données, voir Docker Compose
Aucune identificationN'importe qui peut envoyer n'importe quel scoreUne clé d'API, puis de vrais comptes
Le client déclare son propre scoreTricher est trivialQue le serveur rejoue ou valide la partie
HTTP en clairLes échanges sont lisibles sur le réseauHTTPS

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.
  • GET lit, POST cré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

  1. Lancer l'API, ajouter trois scores avec curl, vérifier que la liste revient triée.
  2. Ouvrir /docs et envoyer un score depuis cette page.
  3. Ajouter une route GET /scores/{player} qui renvoie les scores d'un joueur, et 404 s'il n'en a aucun.
  4. Refuser un nombre de tours négatif ou nul. Quel code de statut convient ?
  5. Arrêter le serveur et appeler fetch_scores() depuis un interpréteur Python. Que renvoie la fonction, en combien de temps ?
  6. Écrire le contrat, sans le coder, d'une API de sauvegardes en ligne : quelles routes, quels corps, quels codes ?