FastAPI est un framework Python moderne pour construire des API rapidement, avec des annotations de type, la validation et une documentation OpenAPI automatique. Apprenez les bases et les usages.
FastAPI est un framework Python pour construire des API web rapidement, avec un code clair et une documentation automatique. Vous écrivez de petites fonctions (appelées « endpoints ») qui déclarent quelles données votre API accepte et ce qu'elle renvoie, et FastAPI gère la plomberie web : routage, validation et génération de réponses JSON.
Une API est un ensemble d'URLs qui permet à un logiciel de communiquer avec un autre.
Par exemple, une application météo sur votre téléphone peut appeler une URL comme GET /weather?city=Berlin. Le serveur répond avec des données structurées (généralement du JSON), par exemple la température et les prévisions. L'application n'a pas besoin d'accès direct à la base de données du serveur : elle interroge l'API et affiche le résultat.
FastAPI vous aide à créer ces URLs et réponses en Python.
Vous n'avez pas besoin d'être expert en async pour commencer ; vous pouvez écrire des endpoints simples et adopter des patterns plus avancés au fur et à mesure.
FastAPI s'est rapidement imposé parce qu'il supprime beaucoup de frictions rencontrées au quotidien pour construire des API en Python.
Les projets API traditionnels commencent souvent par une configuration lente et beaucoup de « plomberie » :
Les fonctionnalités principales de FastAPI ciblent directement ces problèmes, pour que les équipes passent plus de temps à concevoir des endpoints et moins de temps à se battre avec le framework.
FastAPI s'appuie fortement sur les annotations de type Python. Quand vous déclarez qu'un champ est un int, optionnel, ou une liste de quelque chose, FastAPI utilise cette information pour valider les entrées et façonner les sorties.
Cela réduit les erreurs liées aux types (par exemple traiter un identifiant comme du texte à un endroit et comme un nombre ailleurs) et encourage un comportement d'endpoint cohérent. C'est toujours du Python, mais avec des attentes plus claires intégrées aux signatures de fonction.
Puisque le schéma de l'API est dérivé du code, FastAPI peut générer automatiquement une documentation interactive (OpenAPI + Swagger UI/ReDoc). C'est utile pour la collaboration : les développeurs frontend, QA, et intégrateurs peuvent explorer les endpoints, tester des requêtes et voir les modèles exacts sans attendre une documentation séparée.
FastAPI ne corrigera pas une mauvaise conception d'API. Vous devez toujours faire de bons choix de nommage, versioning, gestion des erreurs et sécurité. Ce qu'il offre, c'est un chemin plus propre de l'« idée » à une « API bien définie » avec moins de surprises.
FastAPI paraît simple une fois que vous comprenez quelques idées de base. Vous n'avez pas besoin de mémoriser les détails internes : reconnaissez juste les pièces mobiles que vous utiliserez au quotidien.
Un framework est un ensemble d'outils et de conventions pour construire une API sans repartir de zéro. FastAPI fournit la plomberie pour les tâches courantes : définir des endpoints, lire les entrées, renvoyer des sorties, gérer les erreurs et organiser le code de façon maintenable.
Le routage mappe une URL et une méthode HTTP à un morceau de code Python.
Par exemple, vous pouvez router GET /users vers « lister les utilisateurs » et POST /users vers « créer un utilisateur ». Dans FastAPI, on définit généralement les routes avec des décorateurs comme @app.get(...) et @app.post(...), ce qui permet de voir d'un coup d'œil ce que propose votre API.
Chaque appel d'API est une requête (ce que le client envoie) et une réponse (ce que le serveur renvoie).
FastAPI vous aide à :
/users/{id}), la query string (?page=2), les headers et le corps de la requête200, 201, 404)FastAPI s'exécute sur ASGI, une norme moderne pour les serveurs web Python. Concrètement, cela signifie que FastAPI est conçu pour gérer efficacement de nombreuses connexions et peut supporter des fonctionnalités comme les connexions longue durée (par ex. WebSockets) sans que vous ayez à gérer le réseau bas niveau.
Les annotations de type Python (comme str, int, list[Item]) ne sont pas que de la doc dans FastAPI : elles servent d'entrée essentielle. FastAPI les utilise pour comprendre les données attendues, convertir les valeurs entrantes au bon type et produire des APIs plus prévisibles.
Les modèles Pydantic vous permettent de définir la forme des données (champs, types, valeurs optionnelles) en un seul endroit. FastAPI utilise ces modèles pour valider le JSON entrant, rejeter les entrées invalides avec des messages d'erreur utiles, et sérialiser les sorties de manière cohérente — ainsi votre API se comporte de façon fiable même si les clients envoient des données désordonnées.
Les applications FastAPI sont construites autour des endpoints : un chemin URL plus une méthode HTTP. Pensez à un endpoint comme « ce que le client demande » et « comment il le demande ». Par exemple, un client peut GET /users pour lister les utilisateurs, ou POST /users pour en créer un.
Un chemin est la route, et la méthode est l'action :
GET /products → récupérer des donnéesPOST /products → envoyer des données pour créer quelque chosePUT /products/123 → remplacer/mettre à jour quelque choseDELETE /products/123 → supprimer quelque choseFastAPI sépare les données faisant partie du chemin des données optionnelles de type « filtres ».
GET /users/42 → 42 est l'ID utilisateur.? et généralement optionnel.
GET /users?limit=10&active=true → limit et active contrôlent le rendu des résultats.Quand un client envoie des données structurées (généralement du JSON), elles vont dans le corps de la requête, le plus souvent avec POST ou PUT.
Exemple : POST /orders avec du JSON comme { "item_id": 3, "quantity": 2 }.
FastAPI peut retourner des objets Python simples (comme des dicts), mais il brille quand vous définissez un modèle de réponse. Ce modèle fait office de contrat : les champs sont toujours structurés de la même façon, les données supplémentaires peuvent être filtrées, et les types sont appliqués. Le résultat : des APIs plus propres — les clients savent à quoi s'attendre et vous évitez des réponses « surprises » qui cassent les intégrations.
« Async » (asynchrone) est une façon pour votre API de gérer beaucoup de requêtes efficacement lorsqu'une grande partie du temps est passée à attendre.
Imaginez un barista prenant des commandes. S'il devait rester immobile pendant que la machine à espresso tourne, il servirait moins de clients. Une meilleure façon est : lancer le café, puis prendre la commande suivante pendant que la machine fonctionne.
L'async fonctionne de la même manière. Votre application FastAPI peut démarrer une opération qui attend quelque chose de lent — comme une requête réseau ou une requête BD — et pendant l'attente, elle peut traiter d'autres requêtes entrantes.
L'async est utile quand votre API effectue beaucoup d'opérations I/O (entrées/sorties) — des tâches qui passent du temps à attendre plutôt qu'à « calculer ». Exemples courants :
Si vos endpoints attendent fréquemment ces opérations, l'async peut améliorer le débit et réduire le risque d'accumulation de requêtes sous charge.
L'async n'est pas une baguette magique pour tout accélérer. Si votre endpoint est surtout CPU-bound — par exemple redimensionner de grandes images, exécuter des calculs data science ou chiffrer de gros payloads — l'async n'accélérera pas le calcul lui-même. Dans ces cas, il faut d'autres tactiques (workers en arrière-plan, pools de process, ou mise à l'échelle horizontale).
Vous n'avez pas à tout réécrire pour utiliser FastAPI. Vous pouvez écrire des fonctions de route classiques (sync) et FastAPI les exécutera correctement. Beaucoup de projets mélangent les deux styles : gardez les endpoints simples en synchrone, et utilisez async def là où c'est clairement utile (autour d'appels BD ou HTTP externes en général).
La validation est le point de contrôle entre le monde extérieur et votre code. Quand une API accepte une entrée (corps JSON, params de requête, params de chemin), vous voulez vous assurer qu'elle est complète, du bon type et dans des limites raisonnables — avant d'écrire en base, d'appeler un autre service, ou de déclencher la logique métier.
FastAPI s'appuie sur Pydantic pour ça. Vous décrivez une fois ce que signifie « bonne donnée », et FastAPI :
Si un client envoie des données mal formées, FastAPI répond avec 422 Unprocessable Entity et une charge d'erreur structurée qui pointe le champ exact et la raison. Cela aide les développeurs clients à corriger rapidement les requêtes sans deviner.
Voici un petit modèle montrant champs requis, types, contraintes min/max et formats :
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email doit être présent.age doit être un entier.age est limité à 13–120.EmailStr impose une forme d'email valide.Les mêmes modèles peuvent façonner la sortie, ainsi vos réponses d'API ne fuient pas accidentellement des champs internes. Vous retournez des objets Python ; FastAPI (via Pydantic) les transforme en JSON avec les bons noms de champs et types.
Une des fonctionnalités les plus pratiques de FastAPI est la génération automatique de documentation API — à partir du code que vous avez déjà écrit.
OpenAPI est une manière standard de décrire une API de façon structurée (souvent en JSON). Pensez-y comme à un « contrat » qui détaille :
GET /users/{id})Comme c'est lisible par machine, des outils peuvent l'utiliser pour générer des clients, valider des requêtes et aligner les équipes.
FastAPI sert automatiquement deux pages de doc conviviales :
Dans un projet FastAPI typique, vous les trouverez à :
/docs (Swagger UI)/redoc (ReDoc)Quand vous changez vos paramètres de chemin, modèles de requête, modèles de réponse ou règles de validation, le schéma OpenAPI (et les pages de docs) se mettent à jour automatiquement. Pas d'étape séparée de « maintenance de la doc ».
Une appli FastAPI peut être minuscule et déjà « réelle ». Vous définissez un objet Python appelé app, ajoutez quelques routes et lancez un serveur local pour l'essayer dans votre navigateur.
Voici l'exemple le plus petit utile :
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
C'est tout : une route (GET /) qui renvoie du JSON.
Pour que ça ressemble à une API, stockons des items dans une liste. Ce n'est pas une base de données : les données se réinitialisent au redémarrage du serveur — parfait pour apprendre.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
return item
@app.get("/items")
def list_items():
return items
Vous pouvez maintenant :
POST /items?name=Coffee pour ajouter un itemGET /items pour récupérer la listeUne structure de départ courante est :
main.py (crée app et les routes)requirements.txt ou pyproject.toml (dépendances)Vous faites généralement :
uvicorn main:app --reload)http://127.0.0.1:8000 et tester les endpointsLes « dépendances » FastAPI sont des entrées partagées dont vos endpoints ont besoin — base de données, utilisateur courant authentifié, paramètres d'application, ou paramètres de requête communs. Plutôt que de créer ou parser tout cela dans chaque route, vous les définissez une fois et FastAPI les fournit là où c'est nécessaire.
Une dépendance est généralement une fonction (ou une classe) qui renvoie une valeur utilisée par votre endpoint. FastAPI l'appelle pour vous, comprend ce dont elle a besoin (d'après ses paramètres) et injecte le résultat dans votre fonction d'opération de chemin.
C'est souvent appelé injection de dépendances, mais vous pouvez le voir comme : « déclarez ce dont vous avez besoin, et FastAPI le branche pour vous. »
Sans dépendances, vous pourriez :
Avec des dépendances, vous centralisez cette logique. Si vous changez la façon de créer une session DB ou de charger l'utilisateur courant, vous mettez à jour un seul endroit — pas des dizaines d'endpoints.
page/limitVoici le schéma conceptuel courant dans beaucoup d'apps FastAPI :
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Vous déclarez la dépendance avec Depends(...) et FastAPI passe son résultat en paramètre. Le même principe fonctionne pour des blocs plus complexes (comme get_db() ou get_current_user()), aidant votre code à rester propre au fur et à mesure que l'API grandit.
FastAPI n'« assure » pas automatiquement la sécurité de votre API — vous choisissez un schéma et l'intégrez à vos endpoints. La bonne nouvelle : FastAPI offre des briques (notamment via son système de dépendances) qui rendent les patterns de sécurité courants faciles à implémenter.
Authentification répond à : « Qui êtes-vous ? » Autorisation répond à : « Que pouvez-vous faire ? »
Exemple : un utilisateur peut être authentifié (login/token valide) mais ne pas être autorisé à accéder à une route réservée aux admins.
X-API-Key). Prévoir rotation et révocation.FastAPI supporte ces patterns via des utilitaires comme fastapi.security et les documente proprement dans OpenAPI.
Si vous stockez des mots de passe, ne les stockez jamais en clair. Stockez un hash lent salé (ex. bcrypt/argon2 via une bibliothèque éprouvée). Pensez aussi au rate limiting et aux politiques de verrouillage de compte.
La sécurité tient aux détails : stockage des tokens, réglages CORS, HTTPS, gestion des secrets et vérification des contrôles d'autorisation sur chaque endpoint sensible. Traitez les helpers intégrés comme un point de départ et validez votre approche par des revues et des tests avant de les utiliser en production.
Les tests transforment la promesse « ça marche sur ma machine » en confiance pour la mise en production. La bonne nouvelle : FastAPI repose sur Starlette, vous offrant de bons outils de test sans beaucoup de configuration.
Tests unitaires ciblent de petites pièces : une fonction qui calcule une valeur, une dépendance qui charge l'utilisateur courant, ou une méthode de service qui parle à la BD (souvent mockée).
Tests d'intégration exercent l'API de bout en bout : vous appelez un endpoint et assertiez la réponse HTTP complète. Ce sont eux qui attrapent les erreurs de routage, de wiring des dépendances et de validation.
Une suite saine contient généralement plus de tests unitaires (rapides) et moins de tests d'intégration (plus de confiance).
Les apps FastAPI peuvent être testées « comme un client » en utilisant TestClient de Starlette, qui envoie des requêtes à votre appli en-process — pas besoin de serveur externe.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Testez ce dont dépendent les utilisateurs et autres systèmes :
Utilisez des données prévisibles, isolez les services externes (mock ou BD de test) et évitez l'état partagé entre tests. Les tests rapides sont exécutés ; les tests lents sont souvent ignorés.
Mettre une appli FastAPI en ligne consiste surtout à choisir le bon « runner » et ajouter quelques essentiels de production.
Quand vous lancez uvicorn main:app --reload en local, vous utilisez une configuration de développement : reload automatique, erreurs verbeuses et réglages pensés pour la commodité.
En production, on lance généralement Uvicorn sans reload, souvent derrière un gestionnaire de processus (par ex. Gunicorn avec des workers Uvicorn) ou derrière un reverse proxy. L'objectif : stabilité, redémarrages contrôlés et performances prévisibles.
Un pattern courant :
Cela permet d'avoir une base de code déployable sur plusieurs environnements sans modifier de fichiers.
Avant de déclarer l'application « prête », vérifiez :
/health pour la supervision et les load balancers.Si vous passez de « ça marche localement » à « prêt à livrer », il est aussi utile de standardiser la génération et la gestion du contrat API. Certaines équipes utilisent la sortie OpenAPI de FastAPI dans des workflows automatisés — par ex. générer des clients, valider des requêtes en CI, et déployer de façon cohérente. Des outils peuvent s'intégrer à cette étape pour décrire et exporter l'API depuis un workflow conversationnel ou de prototypage.
FastAPI est un très bon choix quand vous voulez une façon moderne et propre de construire des API REST en Python — surtout si vous tenez à des modèles de requête/réponse clairs et à un comportement prévisible à mesure que l'API grandit.
FastAPI brille dans :
FastAPI n'est pas toujours la réponse la plus simple :
FastAPI peut être très rapide en pratique, mais les performances dépendent surtout de vos appels BD, latence réseau et logique métier. Attendez-vous à un bon débit et une latence correcte pour des charges API typiques — évitez d'imaginer que le framework seul « réparera » des I/O lentes ou des requêtes inefficaces.
Si FastAPI semble correspondre, concentrez-vous ensuite sur les patterns de routage, les modèles Pydantic, l'intégration DB, les tâches en arrière-plan et l'authentification de base.
Un chemin pratique est de construire un petit ensemble d'endpoints, puis d'étendre avec des dépendances réutilisables et des tests à mesure que l'API grandit. Pour accélérer le scaffolding initial (routes, modèles et une structure prête pour le déploiement), vous pouvez utiliser des workflows de prototypage qui mappent vos endpoints avant d'écrire le code. Cela aide à itérer rapidement puis exporter un projet prêt pour la revue et le déploiement.
FastAPI est un framework web Python pour construire des API avec un minimum de code. Vous écrivez des fonctions d'endpoint (par exemple @app.get("/users")) et FastAPI s'occupe du routage, du parsing des requêtes, de la validation et des réponses JSON.
Un avantage clé est que vos annotations de types et vos modèles Pydantic servent de contrat explicite pour ce que l'API accepte et renvoie.
Une API est un ensemble d'URLs (endpoints) que d'autres logiciels peuvent appeler pour échanger des données.
Par exemple, un client peut demander les données météo avec GET /weather?city=Berlin, et le serveur répond avec du JSON structuré. Le client n'a pas besoin d'accès direct à la base de données — il utilise simplement la réponse de l'API.
Le routage associe une méthode HTTP + un chemin à une fonction Python.
Dans FastAPI, on utilise généralement des décorateurs :
@app.get("/items") pour lire des ressources@app.post("/items") pour créer des ressources@app.put("/items/{id}") pour mettre à jour/remplacerLes paramètres de chemin font partie de la structure de l'URL et identifient généralement une ressource précise (ils sont requis).
GET /users/42 → 42 est un paramètre de cheminLes paramètres de requête sont ajoutés après ? et servent de filtres ou contrôles optionnels.
Les modèles Pydantic définissent la forme et les règles de vos données (types, champs requis, contraintes). FastAPI les utilise pour :
Si la validation échoue, FastAPI répond généralement avec 422 Unprocessable Entity et des détails sur le champ en erreur.
FastAPI génère automatiquement un schéma OpenAPI à partir de vos endpoints, annotations de type et modèles.
Vous obtenez généralement deux pages de documentation interactives gratuitement :
/docs/redocComme le schéma est dérivé du code, la documentation reste synchronisée lorsque vous modifiez paramètres et modèles.
Utilisez async def quand votre endpoint passe du temps à attendre des opérations I/O (appels BD, requêtes HTTP externes, accès au stockage).
Privilégiez def lorsque :
Il est courant de mixer des endpoints sync et async dans la même application.
Les dépendances sont des « blocs réutilisables » que FastAPI injecte dans vos endpoints via Depends().
Elles servent souvent à :
Elles réduisent la répétition et centralisent la logique transversale — une modification se fait en un seul endroit.
FastAPI n'assure pas la sécurité par défaut — vous choisissez le schéma et l'intégrez dans vos endpoints. Les approches courantes incluent :
X-API-Key)Pensez aussi aux bonnes pratiques :
Pour les tests, utilisez TestClient de FastAPI/Starlette pour appeler votre API en processus (pas besoin de server externe).
Vérifiez en pratique :
Pour le déploiement, exécutez un serveur ASGI (Uvicorn), généralement derrière un gestionnaire de processus ou un reverse proxy, et ajoutez des éléments de production : logs, checks de santé (), timeouts et configuration par environment.
@app.delete("/items/{id}") pour supprimerCela rend la surface de votre API facile à lire directement dans le code.
GET /users?limit=10&active=true → limit, active sont des paramètres de requête/health