Environnement et premier point de terminaison

Ce que vous saurez faire

Exécutez votre propre API sur votre ordinateur et prouvez qu’elle répond. Toutes les leçons suivantes partent de ce projet et de cette vérification.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 35 minutes

Ce que vous devez savoir

• Comment créer et activer un environnement virtuel, puis consigner les versions, dans Isoler les dépendances : exemple détaillé : créer et utiliser un environnement et Isoler les dépendances : noter les versions.
• Ce qu’est un paquet, dans Modules et importations : la nouvelle organisation.
• Comment envoyer une requête avec curl et lire la réponse, dans Examiner une requête : exemple détaillé : une requête et sa réponse.

Ce qu’il vous faut sur votre ordinateur

• Python 3.12 ou une version plus récente, dans Installer et vérifier Python : Étape 1 : installer Python.
• Le dossier ~/projects, où le cours Python conserve ticket-cleaner. Vous l’avez créé dans Les fichiers et le terminal : exercice guidé : créer votre dossier de projet. S’il manque, exécutez d’abord mkdir ~/projects.
• Une connexion Internet pour installer FastAPI (environ 25 Mo).

Testé avec Python 3.14.6 et FastAPI 0.142.2 sur macOS.

Ce que fait FastAPI

Une API Web a besoin de deux parties. Un programme serveur écoute sur un port, lit le texte HTTP de chaque requête et écrit celui de chaque réponse. Un cadriciel transforme cette requête en appel à l’une de vos fonctions Python. Il transforme ensuite la valeur renvoyée par la fonction en réponse.

FastAPI est un cadriciel Python pour les API. Vous écrivez des fonctions ordinaires avec des annotations de type. FastAPI utilise ces annotations pour lire les données d’entrée, les vérifier, convertir la sortie en JSON et rédiger la documentation. Le programme serveur qui l’exécute est Uvicorn. FastAPI l’installe pour vous et le démarre avec une seule commande.

Un point de terminaison est une méthode et un chemin auxquels l’API répond, par exemple GET /health. Chaque point de terminaison a une fonction Python.

Étape 1 : créer le projet

Le projet de ce cours est ticket-api, à côté du projet ticket-cleaner du cours Python.

1. Créez le dossier du projet et accédez-y :

   mkdir ~/projects/ticket-api
   cd ~/projects/ticket-api

2. Créez et activez un environnement virtuel :

   macOS

   python3 -m venv .venv
   source .venv/bin/activate

   Windows

   python -m venv .venv
   .venv\Scripts\Activate.ps1

   Linux

   python3 -m venv .venv
   source .venv/bin/activate

   L’invite commence par (.venv).

3. Installez FastAPI avec ses outils standard. Les guillemets sont nécessaires, car [ ] a un sens particulier dans certains terminaux :

   python -m pip install "fastapi[standard]==0.142.2"

   [standard] ajoute les outils utilisés dans ce cours : Uvicorn, la commande fastapi et httpx.

4. Consignez les dépendances, comme dans le cours Python :

   requirements.txt

   # Needed to run the API
   fastapi[standard]==0.142.2

   python -m pip freeze > requirements-lock.txt

   Le fichier de verrouillage compte environ 56 lignes : FastAPI, Uvicorn, Pydantic et les paquets dont ils ont besoin.

Les fichiers qui restent sur votre ordinateur

Créez le fichier .gitignore dans ticket-api, comme dans Qualité et passation : une structure de projet claire :

.gitignore

.venv/
__pycache__/
.pytest_cache/
.env
.fastapicloud/

Chaque ordinateur recrée l’environnement et les caches, et .env peut contenir des secrets. Ces fichiers ne doivent donc pas quitter votre ordinateur. Git et la commande de déploiement du module 7 excluent tous les fichiers indiqués dans .gitignore. La plupart de ces fichiers n’existent pas encore : les leçons suivantes les créent.

Étape 2 : le premier point de terminaison

Le code va dans un paquet, ticket_api, comme dans Modules et importations. Créez le dossier ticket_api avec deux fichiers :

ticket_api/__init__.py

"""A small API that classifies support tickets."""

ticket_api/main.py

from fastapi import FastAPI

app = FastAPI(title="Ticket Classifier API")


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}

Ligne	Signification
app = FastAPI(...)	L’objet application. Le serveur lui transmet chaque requête.
@app.get("/health")	Un décorateur : il enregistre la fonction qui suit comme point de terminaison GET /health.
def health() -> dict[str, str]:	Une fonction ordinaire. Le type de retour indique à FastAPI ce que contient la réponse.
return {"status": "ok"}	FastAPI transforme le dictionnaire en corps JSON, avec le statut 200.

Un point de terminaison de santé répond « le service fonctionne ». Il ne fait aucun travail réel, alors il est rapide et échoue très rarement. Les plateformes d’hébergement et les outils de surveillance l’appellent pour vérifier que le service est actif. Chaque API de ce cours en possède un.

Étape 3 : démarrer le serveur

Terminal

fastapi dev ticket_api/main.py

Sortie

 ⚡️ Starting FastAPI in development mode

 🐍 Using import string: ticket_api.main:app

 🌐 Server started at http://127.0.0.1:8000
    Documentation at http://127.0.0.1:8000/docs

  Logs:

INFO:     Will watch for changes in these directories: ['/Users/amira/projects/ticket-api']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [48081] using WatchFiles
INFO:     Started server process [48088]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

fastapi dev démarre Uvicorn en mode développement. Il écoute uniquement sur votre ordinateur (127.0.0.1), sur le port 8000. Il redémarre le serveur chaque fois que vous enregistrez un fichier Python. Le terminal reste occupé pendant que le serveur fonctionne. C’est normal : il attend des requêtes.

Étape 4 : vérifier le fonctionnement

Ouvrez un deuxième terminal, car le premier exécute le serveur. Envoyez ensuite une requête :

Second terminal (on Windows: curl.exe)

curl -i http://127.0.0.1:8000/health

Sortie

HTTP/1.1 200 OK
date: Tue, 06 Oct 2026 20:39:29 GMT
server: uvicorn
content-length: 15
content-type: application/json

{"status":"ok"}

Dans le premier terminal, le serveur écrit une ligne de journal pour chaque requête :

First terminal

INFO:     127.0.0.1:59501 - "GET /health HTTP/1.1" 200 OK

Vous pouvez aussi ouvrir http://127.0.0.1:8000/health dans votre navigateur. Il affiche le même JSON.

Pour arrêter le serveur, allez dans son terminal et appuyez sur Ctrl+C.

Étape 5 : un README pour le projet

Le projet fonctionne maintenant. Notez donc comment l’exécuter. Un README explique à la prochaine personne, et à vous dans un mois, comment configurer et démarrer le projet. Créez README.md dans ticket-api :

README.md

# ticket-api

A small web API that classifies support tickets.

## Set up

```sh
python3 -m venv .venv                # Windows: python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\Activate.ps1
python -m pip install -r requirements-lock.txt
```

## Run

```sh
fastapi dev ticket_api/main.py       # http://127.0.0.1:8000
```

Gardez-le court pour l’instant. Quand une leçon suivante modifie une commande, modifiez-la aussi dans le README. Les sections suivent Qualité et passation : le README.

Exercice guidé : votre API en marche

1. Faites les étapes 1 à 5 sur votre ordinateur.

2. Demandez un chemin qui n’existe pas : curl -i http://127.0.0.1:8000/nothing.

   Le statut est 404 Not Found (introuvable), et le corps est {"detail":"Not Found"}. FastAPI répond pour vous à chaque chemin inconnu.

3. Modifiez le point de terminaison de santé pour qu’il renvoie {"status": "ok", "service": "ticket-api"}. Adaptez le type de retour. Enregistrez le fichier.

   Dans le terminal du serveur, vous voyez qu’il redémarre tout seul. Envoyez la requête à nouveau : le nouveau champ est là.

4. Arrêtez le serveur avec Ctrl+C, puis envoyez la requête à nouveau. Lisez l’erreur et dites à quelle étape du module 1 elle a échoué.

5. Rétablissez le point de terminaison pour qu’il renvoie {"status": "ok"}, puis redémarrez le serveur.

Afficher la réponse à l’étape 4

curl répond Failed to connect to 127.0.0.1 port 8000 after 0 ms: Couldn't connect to server (échec de connexion au serveur). La requête a échoué à l’étape de connexion : aucun programme n’écoute plus sur le port 8000. Il n’y a aucun code de statut, car aucune application n’a répondu.

À vous de jouer : un deuxième point de terminaison

Ajoutez un point de terminaison GET /version qui renvoie {"version": "0.1.0"}. Vérifiez-le avec curl et dans le navigateur. Faites ensuite une prédiction : que renvoie curl -i -X POST http://127.0.0.1:8000/version, et pourquoi?

Afficher la réponse

ticket_api/main.py (add)

@app.get("/version")
def version() -> dict[str, str]:
    return {"version": "0.1.0"}

Le POST renvoie 405 Method Not Allowed (méthode non autorisée) avec {"detail":"Method Not Allowed"}. Le chemin existe, mais seulement pour GET. La réponse contient aussi l’en-tête allow: GET, qui indique au client les méthodes autorisées. Vous pouvez maintenant supprimer ce point de terminaison. Les prochaines leçons ne l’utilisent pas.

Erreur courante

Adresse déjà utilisée

Symptôme : fastapi dev s’arrête immédiatement avec une erreur comme l’une de celles-ci :

ERROR:    [Errno 48] Address already in use
ERROR:    [Errno 98] Address already in use
ERROR:    [WinError 10048] Only one usage of each socket address is normally permitted

Cause : un autre programme écoute déjà sur le port 8000. C’est généralement la même API, encore active dans un autre terminal ou un onglet de terminal oublié. Un seul programme peut écouter sur un port.

Solution :

1. Trouvez l’autre terminal qui exécute fastapi dev et arrêtez le serveur avec Ctrl+C.
2. Si vous ne le trouvez pas, utilisez un autre port pour l’instant : fastapi dev ticket_api/main.py --port 8001. Utilisez alors 8001 dans vos requêtes.
3. Fermer toutes les fenêtres de terminal arrête aussi les serveurs que vous y avez démarrés.

Vérifiez votre compréhension

Vous appelez GET /health, et l'API répond 200. Qu'est-ce que cela prouve, et qu'est-ce que cela ne prouve pas?

Afficher la réponse

Cela prouve que le serveur fonctionne, écoute sur le port et que l’application traite les requêtes. Cela ne prouve pas que le travail réel fonctionne. Dans les leçons suivantes, le classificateur pourrait être en panne alors que /health répond encore 200. Le module 7 ajoute une deuxième vérification, /ready, pour cela.

Récapitulatif

• FastAPI transforme les requêtes HTTP en appels à vos fonctions. Uvicorn est le programme serveur qui l’exécute.
• Un point de terminaison est une méthode et un chemin, enregistrés avec un décorateur comme @app.get("/health").
• fastapi dev ticket_api/main.py démarre un serveur de développement sur http://127.0.0.1:8000, qui redémarre quand vous enregistrez.
• Gardez le serveur dans un terminal et envoyez les requêtes depuis un deuxième terminal.
• Un point de terminaison de santé prouve que le service fonctionne.
• .gitignore garde l’environnement, les caches et les secrets sur votre ordinateur. Le README explique comment configurer et exécuter le projet.

Ensuite, vous ajoutez le vrai point de terminaison : il lit un billet de soutien en JSON, le vérifie et renvoie une classification.

Leçon suivante : Modèles de requête et de réponse