FastAPI : créer une API REST en Python

FastAPI est le framework moderne pour écrire une API REST en Python. À partir de simples annotations de type, il génère automatiquement la validation des données et une documentation interactive OpenAPI. Ce guide vous fait construire une vraie API de zéro : installation, premières routes, validation Pydantic, gestion des erreurs et documentation auto. Tout est vérifié sur FastAPI 0.138 (Pydantic 2, Python 3.12).

Cette page est le volet pratique du concept : si vous cherchez d'abord ce qu'est une API REST, lisez API REST : définition et bonnes pratiques.

Ce que vous allez apprendre

• Installer FastAPI et le serveur Uvicorn
• Écrire des routes GET et POST avec des annotations de type
• Valider les données d'entrée automatiquement avec Pydantic
• Renvoyer les bons codes HTTP et gérer les erreurs (404)
• Profiter de la documentation OpenAPI générée toute seule

Qu'est-ce que FastAPI ?

FastAPI est un framework web Python pour construire des API, bâti sur Starlette (asynchrone) et Pydantic (validation). Son idée maîtresse : vous typez vos fonctions et vos modèles de données, et FastAPI en déduit tout le reste.

• Le type d'un paramètre devient une règle de validation : une donnée invalide est rejetée avec une erreur claire, sans une ligne de code en plus.
• Les modèles Pydantic décrivent vos objets : FastAPI les sérialise en JSON et vérifie chaque champ.
• La documentation OpenAPI (Swagger UI sur /docs) est générée automatiquement à partir de ces types.

C'est ce qui le distingue de Flask : là où Flask est minimaliste et vous laisse tout câbler, FastAPI vous donne validation et documentation gratuitement.

Prérequis

• Python 3.9 ou supérieur (3.12 utilisé ici).
• De quoi isoler les dépendances : un environnement virtuel ou uv.

Installer FastAPI

FastAPI a besoin d'un serveur ASGI pour tourner : Uvicorn. On installe les deux d'un coup, dans un environnement isolé.

uv

uv pip install fastapi "uvicorn[standard]"

pip

pip install fastapi "uvicorn[standard]"

Les versions au moment de ce guide : FastAPI 0.138, Pydantic 2.13, Uvicorn 0.49.

Votre première API

Créez un fichier main.py. On expose un petit inventaire de serveurs : un modèle Pydantic décrit un serveur, et quelques routes le manipulent.

main.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="API Inventaire serveurs", version="1.0.0")

class Serveur(BaseModel):
    hostname: str = Field(min_length=1, examples=["web-prod-01"])
    ip: str
    env: str = "prod"

# "base de données" en mémoire pour l'exemple
serveurs: dict[int, Serveur] = {
    1: Serveur(hostname="web-prod-01", ip="10.0.1.10", env="prod"),
}

@app.get("/serveurs")
def lister_serveurs() -> list[Serveur]:
    return list(serveurs.values())

@app.get("/serveurs/{serveur_id}")
def lire_serveur(serveur_id: int) -> Serveur:
    if serveur_id not in serveurs:
        raise HTTPException(status_code=404, detail="Serveur introuvable")
    return serveurs[serveur_id]

@app.post("/serveurs", status_code=201)
def creer_serveur(serveur: Serveur) -> Serveur:
    nouvel_id = max(serveurs) + 1
    serveurs[nouvel_id] = serveur
    return serveur

Trois choses à noter : le décorateur @app.get(...) associe une route à une fonction, le paramètre serveur_id: int convertit et valide l'URL, et le type de retour -> Serveur documente la réponse.

Lancer le serveur

Uvicorn sert l'application. L'option --reload recharge à chaud à chaque modification, pratique en développement.

uvicorn main:app --reload

Le main:app signifie « l'objet app du module main ». Testons les routes avec curl :

curl http://127.0.0.1:8000/serveurs
# [{"hostname":"web-prod-01","ip":"10.0.1.10","env":"prod"}]

curl -X POST http://127.0.0.1:8000/serveurs \
  -H "Content-Type: application/json" \
  -d '{"hostname":"db-prod-01","ip":"10.0.1.20","env":"prod"}'
# 201 → {"hostname":"db-prod-01","ip":"10.0.1.20","env":"prod"}

Une ressource absente renvoie le bon code grâce à HTTPException :

curl -i http://127.0.0.1:8000/serveurs/99
# HTTP/1.1 404 Not Found
# {"detail":"Serveur introuvable"}

La validation automatique

C'est l'atout majeur de FastAPI. Notre champ hostname est déclaré Field(min_length=1). Envoyez un hostname vide :

curl -X POST http://127.0.0.1:8000/serveurs \
  -H "Content-Type: application/json" \
  -d '{"hostname":"","ip":"10.0.0.1"}'

FastAPI répond 422 avec une erreur précise, sans que vous ayez écrit le moindre if :

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "hostname"],
      "msg": "String should have at least 1 character",
      "ctx": {"min_length": 1}
    }
  ]
}

Le champ loc indique exactement où est l'erreur. C'est Pydantic qui travaille : vos types sont le contrat, et le contrat est appliqué tout seul.

La documentation, générée toute seule

Ouvrez http://127.0.0.1:8000/docs : FastAPI affiche une interface Swagger UI interactive où l'on peut essayer chaque route. Le schéma brut est sur /openapi.json :

curl -s http://127.0.0.1:8000/openapi.json | head
# {"openapi":"3.1.0","info":{"title":"API Inventaire serveurs",...}

Vous obtenez une spécification OpenAPI 3.1 complète, dérivée de vos types, sans aucune configuration. Pour comprendre ce que vous générez là, voyez les bonnes pratiques d'une API REST.

Mon réflexe en lab

Je garde /docs ouvert dans un onglet pendant que je code : à chaque --reload, la doc reflète mes changements en direct, et je teste les routes sans écrire de client. C'est le meilleur moyen de vérifier qu'un modèle Pydantic fait bien ce que je crois, surtout pour les cas d'erreur.

Pièges courants

Piège	Conséquence	Solution
Oublier Uvicorn	uvicorn: command not found	Installer uvicorn[standard]
Mauvais main:app	Error loading ASGI app	Format fichier:variable (sans .py)
Confondre Pydantic 1 et 2	Erreurs de validateurs/config	FastAPI récent exige Pydantic 2
Pas de type sur le corps	Données non validées	Déclarer un modèle Pydantic en paramètre
--reload en production	Instabilité, surcoût	--reload en dev seulement ; en prod, plusieurs workers

Glissez pour voir

À retenir

• FastAPI construit des API REST en Python à partir d'annotations de type.
• La validation des entrées est automatique via Pydantic (erreurs 422 précises).
• La documentation OpenAPI / Swagger (/docs) est générée toute seule.
• On lance l'app avec uvicorn main:app --reload en développement.
• FastAPI donne gratuitement ce que Flask vous fait câbler à la main.

FAQ : questions fréquentes

FastAPI, c'est quoi ?

FastAPI est un framework web Python moderne pour construire des API REST, bâti sur Starlette (async) et Pydantic (validation). À partir d'annotations de type, il génère automatiquement la validation des données et une documentation interactive OpenAPI / Swagger.

FastAPI ou Flask : lequel choisir ?

Flask est minimaliste et vous laisse tout câbler (validation, doc). FastAPI fournit gratuitement la validation Pydantic, la documentation OpenAPI et le support async. Flask pour un micro-service très simple ou un existant Flask ; FastAPI pour une API typée, documentée et performante par défaut.

Comment lancer une application FastAPI ?

FastAPI a besoin d'un serveur ASGI : Uvicorn. Après installation, lancez uvicorn main:app --reload, où main est le fichier (main.py) et app l'objet FastAPI. L'option --reload recharge à chaud en développement ; en production, on utilise plusieurs workers sans --reload.

Comment FastAPI valide-t-il les données ?

Via Pydantic et les annotations de type. Vous déclarez un modèle (BaseModel) en paramètre, et FastAPI rejette automatiquement une requête invalide avec un code 422 et une erreur précise indiquant le champ fautif, sans écrire de validation à la main.

Comment voir la documentation d'une API FastAPI ?

FastAPI génère la documentation automatiquement. L'interface Swagger UI interactive est disponible sur /docs, une alternative ReDoc sur /redoc, et le schéma brut OpenAPI 3.1 sur /openapi.json. Aucune configuration n'est nécessaire : la doc dérive de vos types.

Prochaines étapes

API REST : définition et bonnes pratiques Le concept, les méthodes HTTP et les bonnes pratiques avant de coder.

Formation Python Tout le parcours Python : bases, environnements, packaging, IA.

Documentation officielle FastAPI Référence complète : dépendances, sécurité, bases de données, async.

×

📖 Voir la documentation →