# 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](/reseau/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-Type: application/json` | Des précisions sur la requête |
| Corps | `{"player": "Alice", "turns": 42}` | 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 /scores/12` |
| `DELETE` | Supprimer | `DELETE /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.

| 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
{
  "player": "Alice",
  "turns": 42,
  "won": true,
  "cities": ["Lyon", "Brest"]
}
```

| 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](/python/structures-de-donnees/choisir).

## 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.

<Mermaid
  chart={`sequenceDiagram
    participant J as Le jeu
    participant A as API des scores
    Note over J: fin de partie
    J->>A: POST /scores, Alice en 42 tours
    A-->>J: 201 Created
    Note over J: écran d'accueil
    J->>A: GET /scores
    A-->>J: 200 OK et la liste triée`}
/>

## Écrire l'API avec FastAPI

[FastAPI](https://fastapi.tiangolo.com) est une bibliothèque Python pour écrire des API. On crée un dossier `server/` à la racine du projet, séparé du jeu.

```text
server/
├── main.py
└── requirements.txt
```

```text
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 :

```bash
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.

```bash
curl -i http://localhost:8000/scores
```

```text
HTTP/1.1 200 OK
content-type: application/json

[]
```

```bash
curl -i -X POST http://localhost:8000/scores \
  -H "Content-Type: application/json" \
  -d '{"player": "Alice", "turns": 42}'
```

```text
HTTP/1.1 201 Created
content-type: application/json

{"player":"Alice","turns":42}
```

Et une requête incomplète :

```bash
curl -X POST http://localhost:8000/scores \
  -H "Content-Type: application/json" \
  -d '{"player": "Bob"}'
```

```json
{"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.

:::tip{title="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

| 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](/virtualisation/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.
- `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 ?
