Qu'est-ce que FastAPI ? Guide pratique pour construire des API

FastAPI en une minute : définition simple

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.

Qu'est-ce qu'une API ? Un exemple simple

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.

À qui s'adresse FastAPI ?

• Débutants qui veulent une manière moderne et guidée de créer des API sans écrire beaucoup de code répétitif.
• Développeurs solo qui doivent avancer vite tout en gardant un code lisible.
• Équipes construisant des services en production qui tirent profit d'une forte validation, de contrats cohérents et d'une excellente documentation.

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.

Ce que vous apprendrez dans ce guide

• Ce qui distingue FastAPI des autres options Python pour les API
• Comment fonctionnent les requêtes et réponses (et ce que signifie vraiment « async »)
• Comment fonctionne la validation des données avec Pydantic
• Comment FastAPI génère la doc OpenAPI (Swagger UI et ReDoc)
• Comment structurer une appli avec dépendances, sécurité, tests et bases du déploiement

Pourquoi FastAPI a gagné en popularité

FastAPI s'est rapidement imposé parce qu'il supprime beaucoup de frictions rencontrées au quotidien pour construire des API en Python.

Il s'attaque aux problèmes courants des API

Les projets API traditionnels commencent souvent par une configuration lente et beaucoup de « plomberie » :

• Écrire (et maintenir synchronisés) le parsing des requêtes, la validation et les messages d'erreur
• Des contrats d'API peu clairs : que reçoit et renvoie exactement cet endpoint ?
• Une documentation qui prend du retard par rapport au code, surtout quand l'équipe grandit

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.

Les annotations de type font office de contrat

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.

La doc automatique accélère le travail des équipes

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.

Populaire, mais pas magique

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.

Concepts clés à connaître

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.

FastAPI est un framework

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.

Routage : comment les endpoints sont définis

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.

Requêtes et réponses

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 à :

• Lire les données depuis le chemin (/users/{id}), la query string (?page=2), les headers et le corps de la requête
• Retourner des réponses JSON structurées avec les bons codes HTTP (comme 200, 201, 404)

ASGI (haut niveau)

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.

Annotations de type : plus que de la documentation

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.

Modèles Pydantic pour la validation

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.

Comment FastAPI gère les requêtes et réponses

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.

Endpoints = chemins + méthodes

Un chemin est la route, et la méthode est l'action :

• GET /products → récupérer des données
• POST /products → envoyer des données pour créer quelque chose
• PUT /products/123 → remplacer/mettre à jour quelque chose
• DELETE /products/123 → supprimer quelque chose

Paramètres de chemin vs paramètres de requête

FastAPI sépare les données faisant partie du chemin des données optionnelles de type « filtres ».

• Paramètre de chemin : inclus dans la structure de l'URL.
  • Exemple : GET /users/42 → 42 est l'ID utilisateur.
• Paramètre de requête : ajouté après ? et généralement optionnel.
  • Exemple : GET /users?limit=10&active=true → limit et active contrôlent le rendu des résultats.

Corps de requête pour les payloads JSON

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

Modèles de réponse et sorties cohérentes

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 dans FastAPI : ce que c'est et quand ça aide

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

Une analogie quotidienne : attendre de l'I/O

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.

Quand l'async aide le plus

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 :

• Appeler une base de données (surtout sur le réseau)
• Appeler des services externes (paiements, cartes, API mail)
• Lire/écrire des fichiers ou parler à un stockage d'objets

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.

Quand l'async importe peu

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

Bonne nouvelle : le code synchrone fonctionne toujours

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

Validation et sérialisation des données avec Pydantic

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 :

• rejette les mauvaises entrées tôt
• convertit les types quand c'est possible (par ex. transformer "42" en entier)
• retourne des réponses JSON cohérentes (sérialisation)

Attraper les mauvaises entrées tôt (avec des erreurs claires)

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.

Exemples courants de validation

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)

• Champs requis : email doit être présent.
• Types : age doit être un entier.
• Min/max : age est limité à 13–120.
• Formats : EmailStr impose une forme d'email valide.

Sérialisation : renvoyer du JSON propre et prévisible

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.

Docs automatiques : OpenAPI, Swagger UI, ReDoc

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 : un contrat lisible par machine

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 :

• quels endpoints existent (comme GET /users/{id})
• quels paramètres ils acceptent
• à quoi doit ressembler le corps de la requête
• quelles réponses et formats d'erreur sont attendus

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.

Swagger UI et ReDoc : docs interactives prêtes à l'emploi

FastAPI sert automatiquement deux pages de doc conviviales :

• Swagger UI (interactive) : tester les endpoints directement depuis le navigateur
• ReDoc (référence) : une page de documentation claire

Dans un projet FastAPI typique, vous les trouverez à :

• /docs (Swagger UI)
• /redoc (ReDoc)

Docs qui restent synchronisées avec le code

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

Pourquoi cela accélère le travail frontend et QA

• Les développeurs frontend peuvent explorer les endpoints immédiatement et comprendre les champs requis sans attendre une spécification manuelle.
• Le QA peut tester rapidement les cas limites (champs manquants, mauvais types) et voir les réponses d'erreur exactes.
• Tout le monde partage la même source de vérité : l'API en fonctionnement et son contrat OpenAPI.

Votre première appli FastAPI (parcours conceptuel)

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.

1) Un endpoint minimal « hello »

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.

2) Ajouter des endpoints create/read simples (en mémoire)

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 item
• GET /items pour récupérer la liste

3) Petit agencement typique du projet

Une structure de départ courante est :

• main.py (crée app et les routes)
• requirements.txt ou pyproject.toml (dépendances)

4) Lancer en local (conceptuellement)

Vous faites généralement :

1. Installer les dépendances (FastAPI + un serveur ASGI comme Uvicorn)
2. Démarrer le serveur dev (par exemple : uvicorn main:app --reload)
3. Ouvrir http://127.0.0.1:8000 et tester les endpoints

Dépendances et blocs réutilisables

Les « 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.

Ce qu'est une dépendance (en termes simples)

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

Pourquoi cela réduit la répétition

Sans dépendances, vous pourriez :

• Ouvrir/fermer des connexions DB dans chaque endpoint
• Répéter les vérifications d'authentification partout
• Re-parser les mêmes paramètres de pagination dans plusieurs routes

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.

Exemples courants de dépendances

• Session BD : créer une session par requête et la fermer proprement
• Settings/config : fournir la configuration selon l'environnement sans la passer partout
• Pagination : réutiliser le parsing/validation de page/limit
• Auth user : récupérer l'utilisateur courant depuis un token et appliquer les permissions

Comment les dépendances se branchent aux endpoints

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

Bases de la sécurité : authentification et autorisation

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 vs autorisation

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.

Approches d'authentification courantes (haut niveau)

• Clés API : simples pour l'accès service-à-service. Souvent envoyées via un header (ex. X-API-Key). Prévoir rotation et révocation.
• OAuth2 : standard pour l'accès délégué ; courant pour « Se connecter avec … » ou séparer l'authentification de l'API.
• JWT (JSON Web Tokens) : utilisé comme bearer tokens. Pratique pour des APIs sans état, mais il faut gérer l'expiration, les clés de signature et la stratégie de révocation.

FastAPI supporte ces patterns via des utilitaires comme fastapi.security et les documente proprement dans OpenAPI.

Bases du stockage des mots de passe

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.

Une remarque prudente

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.

Tester les applications FastAPI

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 vs tests d'intégration

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

L'idée de TestClient

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

Que tester (checklist pratique)

Testez ce dont dépendent les utilisateurs et autres systèmes :

• Codes de statut (200 vs 201 vs 404 vs 422)
• Erreurs de validation (champs manquants, mauvais types, champs en trop)
• Forme des réponses (clés présentes, types corrects, listes vides gérées)
• Cas limites (zéro résultat, inputs volumineux, dates en bordure)
• Cas d'auth (pas de token, token expiré, rôle insuffisant)

Garder les tests rapides et reproductibles

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.

Déployer FastAPI : options pratiques et checklist

Mettre une appli FastAPI en ligne consiste surtout à choisir le bon « runner » et ajouter quelques essentiels de production.

Serveurs dev vs 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.

Configuration via variables d'environnement

Un pattern courant :

• Stocker les secrets et valeurs spécifiques à l'environnement (URL DB, clés API, origines autorisées) dans des variables d'environnement.
• Garder des valeurs par défaut raisonnables pour l'usage local.
• Charger et valider les settings au démarrage (souvent via Pydantic settings).

Cela permet d'avoir une base de code déployable sur plusieurs environnements sans modifier de fichiers.

Cibles de déploiement courantes (aperçu rapide)

• Conteneurs (Docker/Kubernetes) : populaires pour des builds reproductibles et la mise à l'échelle.
• Machines virtuelles : simples et flexibles ; bonnes si vous gérez vos propres serveurs.
• Serverless : adapté aux petites APIs ; attention aux cold starts et limites des plateformes.

Checklist pratique de déploiement

Avant de déclarer l'application « prête », vérifiez :

• Logging : logs structurés, IDs de requête (si nécessaire) et niveaux de logs par environnement.
• Health checks : endpoints comme /health pour la supervision et les load balancers.
• Gestion des erreurs : réponses JSON d'erreur cohérentes ; ne pas exposer les traces stack aux utilisateurs.
• Timeouts et limites : taille du corps, timeouts workers, et rate limiting si pertinent.
• Politique de docs : décider d'exposer publicement Swagger UI/ReDoc ou de les restreindre.

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.

Quand utiliser FastAPI (et quand ne pas l'utiliser)

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.

Cas d'utilisation idéaux

FastAPI brille dans :

• Services internes où les équipes itèrent vite, veulent des endpoints lisibles et des contrats partagés entre services.
• APIs publiques qui profitent d'une validation stricte et d'une gestion d'erreurs cohérente.
• Microservices où de petites API focalisées sont déployées indépendamment.
• Prototypes et MVPs où l'on veut avancer rapidement sans perdre la structure (validation + docs).

Quand un autre outil peut mieux convenir

FastAPI n'est pas toujours la réponse la plus simple :

• Pour un script ponctuel ou un tout petit webhook, quelque chose de plus léger (ou simplement du Python) peut suffire.
• Si votre projet a besoin de la pile complète Django (ORM, admin, templating, écosystème mature), Django ou Django REST Framework peuvent réduire les décisions et le glue code.

Un mot réaliste sur la performance

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.

Prochaines étapes

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.