Arrive le moment où le code doit répondre à autre chose qu'à toi. Un site web qui veut afficher une liste de produits, une application mobile qui veut enregistrer un compte, un autre programme qui a besoin d'une donnée précise. Le script qui s'exécute une fois et s'arrête ne sait pas faire ça. Il faut un intermédiaire qui reste allumé et qui répond quand on l'appelle.
Cet intermédiaire, c'est une API. Et FastAPI est aujourd'hui le moyen le plus direct d'en construire une en Python. Ce guide part de zéro, sans supposer que tu aies déjà touché à un framework web, et te mène à une API qui tourne, qui valide ses données et qui documente ses routes toute seule.
Le moment où un script ne suffit plus
Prenons un cas simple. Tu as écrit une fonction Python qui prend le prénom d'une personne et renvoie un message de bienvenue. Dans un fichier, avec un print(), ça marche. Tu lances le script, il affiche le message, il se termine.
Maintenant, mets-toi à la place d'une application mobile développée par quelqu'un d'autre. Cette application voudrait afficher le même message de bienvenue à ses utilisateurs. Elle ne peut pas ouvrir ton fichier Python et lancer ta fonction. Elle tourne sur un téléphone, ton code tourne sur un serveur, et les deux ne parlent pas le même langage de programmation. Le seul terrain d'entente possible, c'est le réseau.
Une API répond à ce besoin. Le mot signifie interface de programmation applicative, ce qui ne t'avance pas beaucoup. En pratique, une API web est un programme qui reste allumé sur un serveur, écoute les demandes qui arrivent par le réseau, et renvoie une réponse dans un format que n'importe quelle machine sait lire. Ton code Python continue d'exister, mais il devient accessible depuis l'extérieur.
Ce passage du script isolé au service qui écoute est souvent l'étape qui bloque les personnes en reconversion et les développeurs juniors. Le code Python, tu le tiens déjà. Ce qui manque, c'est la couche qui l'expose au monde. FastAPI s'occupe précisément de cette couche.
Une API REST expliquée sans jargon
REST est un ensemble de conventions pour organiser les échanges entre un client et un serveur sur le web. Personne ne t'oblige à le suivre, mais tout le secteur l'a adopté, donc apprendre ces conventions te permet de lire et de construire des API que les autres comprennent d'emblée.
Trois idées suffisent pour démarrer.
Les URL désignent des ressources
Une ressource, c'est une chose que ton API gère : un utilisateur, un article, une commande. Chaque ressource a une adresse. /articles désigne la collection de tous les articles, /articles/42 désigne l'article numéro 42. L'adresse dit de quoi on parle, pas ce qu'on veut en faire.
Les verbes HTTP disent l'action
C'est le verbe de la requête qui précise l'intention. GET pour lire, POST pour créer, PUT ou PATCH pour modifier, DELETE pour supprimer. La même adresse /articles/42 sert à lire, modifier ou supprimer l'article selon le verbe employé. Cette séparation entre l'adresse et l'action garde les URL propres et prévisibles.
Les réponses voyagent en JSON
Quand ton API répond, elle renvoie des données structurées, presque toujours au format JSON. Ce format ressemble beaucoup à un dictionnaire Python, avec des clés et des valeurs. Un téléphone sous Android, un site en React, un script en Java : tous savent lire du JSON. C'est ce langage commun qui permet à des technologies différentes de communiquer.
Avec ces trois briques, tu peux déjà décrire n'importe quelle petite API. Une adresse, un verbe, une réponse JSON. Le reste, ce sont des détails que tu ajouteras au fur et à mesure.
Pourquoi FastAPI plutôt qu'autre chose
En Python, plusieurs outils permettent de construire une API. Flask reste très répandu, Django propose une machinerie complète, et FastAPI est arrivé plus tard, en 2018, créé par Sebastián Ramírez. Sa particularité tient à une décision de conception : il s'appuie sur les annotations de type de Python pour faire une bonne partie du travail à ta place.
Une annotation de type, c'est cette précision que tu ajoutes derrière un paramètre pour indiquer qu'il attend un entier, un texte ou une date. Avec un framework classique, tu écris ce genre d'indication puis tu vérifies quand même à la main que la donnée reçue est correcte. FastAPI lit l'annotation et en déduit la validation, la conversion et même la documentation. Une seule ligne fait trois choses.
Le gain le plus visible arrive au premier lancement. FastAPI génère automatiquement une page de documentation interactive, accessible à l'adresse /docs, où chaque route est listée avec ses paramètres et un bouton pour l'essayer directement dans le navigateur. Tu n'écris pas une ligne pour obtenir cette page. Pour quelqu'un qui débute, voir son API répondre depuis une interface propre change la façon d'apprendre.
Construire l'API étape par étape
On va monter une petite API qui gère une liste de tâches. Rien de compliqué, mais assez pour toucher les gestes essentiels : lire, créer, gérer un paramètre dynamique. Il te faut Python 3.10 ou plus récent installé sur ta machine. Si l'installation de Python et la création d'un environnement virtuel te semblent floues, la formation Python pour débutants couvre ces bases avant d'attaquer un framework.
Installer FastAPI
Dans un environnement virtuel activé, une seule commande installe FastAPI et le serveur qui l'accompagne :
pip install "fastapi[standard]"Les guillemets autour du nom ne sont pas décoratifs, certains terminaux les exigent pour interpréter les crochets. Le mot standard ajoute Uvicorn, le serveur qui va faire tourner ton API, ainsi que l'outil en ligne de commande pour la lancer.
Ta première route
Crée un fichier main.py et écris ces quelques lignes :
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def accueil():
return {"message": "L'API tourne"}La ligne app = FastAPI() crée ton application. Le @app.get("/") juste au-dessus de la fonction indique que celle-ci répond aux requêtes GET envoyées à l'adresse racine. Le dictionnaire renvoyé sera transformé en JSON sans que tu aies à t'en occuper. Lance le serveur avec :
fastapi dev main.pyOuvre ensuite http://127.0.0.1:8000 dans ton navigateur. Le message apparaît. Va ensuite sur /docs pour voir la documentation générée toute seule.
Un paramètre dans l'URL
Ajoutons une route qui renvoie une tâche selon son numéro. Le numéro fait partie de l'adresse :
@app.get("/taches/{tache_id}")
def lire_tache(tache_id: int):
return {"id": tache_id, "titre": "Exemple"}Regarde l'annotation tache_id: int. Elle fait deux choses. D'abord, elle convertit le numéro reçu dans l'URL en entier Python. Ensuite, si quelqu'un demande /taches/abc, FastAPI refuse la requête avec un message d'erreur clair, avant même que ta fonction ne s'exécute. Tu n'as écrit aucune vérification, l'annotation a suffi.
Recevoir des données avec Pydantic
Pour créer une tâche, le client doit envoyer des informations : un titre, peut-être un statut. Tu décris la forme attendue avec un modèle Pydantic, une classe qui liste les champs et leur type.
from pydantic import BaseModel
class Tache(BaseModel):
titre: str
terminee: bool = False
@app.post("/taches")
def creer_tache(tache: Tache):
return {"cree": tache}Quand une requête POST arrive sur /taches, FastAPI lit le JSON envoyé, vérifie qu'il contient bien un titre en texte, applique la valeur par défaut du champ terminee s'il manque, et te livre un objet Tache propre. Si le titre manque ou si un champ a le mauvais type, la requête est rejetée avec le détail de ce qui cloche. Cette validation gratuite est l'une des raisons pour lesquelles FastAPI a pris autant de place ces dernières années.
Avec ces quatre routes, tu as déjà une API qui lit, crée et gère un paramètre dynamique. Le squelette d'une vraie application se trouve là. La suite consiste à brancher une base de données, à gérer l'authentification, à découper le code en plusieurs fichiers, sujets qu'une formation dédiée à FastAPI déroule dans l'ordre.
Les pièges qui reviennent souvent
Quelques erreurs se répètent chez la plupart des gens qui découvrent FastAPI. Les repérer tôt fait gagner des heures.
Confondre le serveur de dev et la production
La commande fastapi dev lance un serveur qui redémarre à chaque modification du code. Pratique pour développer, inadapté pour un site en ligne. En production, on utilise fastapi run ou une configuration Uvicorn dédiée, sans rechargement automatique et avec des réglages de performance. Mettre le serveur de développement en ligne est une erreur classique qui coûte en stabilité.
Renvoyer les données brutes de la base
Une tentation fréquente consiste à renvoyer directement ce que la base de données contient, mot de passe haché compris. Une API répond à des clients qui ne sont pas forcément de confiance. Définir un modèle de réponse Pydantic distinct, qui ne contient que les champs destinés à sortir, évite de laisser fuiter des informations sensibles. Ce réflexe rejoint des règles de sécurité plus larges que l'on retrouve dans les failles de sécurité les plus courantes des projets juniors.
Négliger les codes de statut HTTP
Par défaut, une route qui réussit renvoie le code 200. Mais créer une ressource devrait renvoyer un 201, une ressource introuvable un 404, une donnée invalide un 422. FastAPI gère certains cas automatiquement, à toi de préciser les autres avec le paramètre status_code ou en levant une HTTPException. Un client qui reçoit toujours 200, même en cas d'erreur, ne peut pas réagir correctement.
Oublier de tester l'API
Cliquer sur les boutons de la page /docs rassure, mais ne remplace pas des tests automatisés. FastAPI fournit un client de test qui permet d'appeler tes routes depuis un fichier de test et de vérifier les réponses. Prendre cette habitude dès le début évite de casser des routes sans s'en rendre compte, un sujet développé dans notre article sur comment écrire des tests utiles.
Aucun de ces pièges n'est grave pris isolément. Ils deviennent coûteux quand ils s'accumulent sur un projet que d'autres personnes vont reprendre.
