FastAPI : ta première API en Python

🎯 Objectif : À la fin de ce chapitre, tu sauras créer une API REST fonctionnelle avec FastAPI — routing, doc auto-générée, et premiers endpoints testables. ⏱️ Durée estimée : 45 minutes | Niveau : Débutant

Tu ouvres ton appli météo. Elle affiche 12°C à Zurich. D’où vient cette info ? L’appli ne mesure rien — elle demande la donnée à un service distant via une API. Tu fais la même chose quand tu lances un terraform apply ou un kubectl get pods : ton CLI envoie des requêtes HTTP à une API.

En tant que DevOps, tu déploies des APIs, tu les monitores, tu debugges leurs erreurs en prod. Savoir en construire une, c’est comprendre ce que tu opères. FastAPI est le framework Python idéal pour ça : rapide, moderne, et pensé pour la productivité.

Ce chapitre pose les fondations : de la théorie HTTP jusqu’à ton premier endpoint fonctionnel.

Pourquoi c’est important

Une API (Application Programming Interface), c’est un contrat entre deux logiciels. L’un expose des fonctionnalités, l’autre les consomme. Le consommateur n’a pas besoin de connaître l’implémentation interne — il respecte le protocole, il obtient sa réponse.

Pense à une prise électrique : deux broches, un voltage standard. Que l’électricité vienne d’un barrage ou d’un panneau solaire, l’interface reste la même. Une API fonctionne pareil — elle abstrait la complexité derrière un contrat simple.

🔥 Cas réel : En 2002, Jeff Bezos a imposé chez Amazon que chaque équipe expose ses fonctionnalités via des APIs. Plus aucune communication directe entre bases de données. Ce mandat a transformé Amazon en plateforme — et donné naissance à AWS. Aujourd’hui, toute architecture microservices repose sur ce même principe.

En DevOps, tu interagis avec des APIs en permanence :

• Déployer des APIs (comprendre leur fonctionnement pour les opérer)
• Créer des outils internes (webhooks, dashboards, endpoints de health check)
• Interagir avec les providers (AWS, GCP, GitHub, PagerDuty — tout est API)
• Debugger en prod (lire les codes HTTP, comprendre pourquoi un 502 arrive)

💡 Tip DevOps : Un endpoint /health qui renvoie {"status": "ok"} est le minimum vital pour toute API en production. C’est ce que tes load balancers et tes outils de monitoring vont interroger.

Comprendre le concept

Les APIs web communiquent via HTTP. Chaque requête se compose de quatre éléments : une URL, une méthode, des headers, et optionnellement un body.

Les méthodes HTTP correspondent aux opérations CRUD :

Les réponses arrivent avec un code de statut qui suit une logique par centaine :

• 2xx — Succès (200 OK, 201 Created)
• 4xx — Erreur client (400 Bad Request, 404 Not Found, 422 Unprocessable Entity)
• 5xx — Erreur serveur (500 Internal Server Error, 503 Service Unavailable)

🧠 À retenir : Un 404 n’est pas une erreur serveur — c’est le client qui demande une ressource inexistante. Un 500, c’est le serveur qui a planté. Savoir distinguer les deux te fait gagner un temps fou en debug.

L’architecture REST (Representational State Transfer) ajoute des conventions : les URLs désignent des ressources (noms au pluriel), les méthodes HTTP expriment l’action. Chaque requête est sans état — le serveur ne stocke rien entre deux appels.

Pour illustrer le bon nommage d’endpoints REST, voici la convention à suivre :

# ✅ REST correct — les URLs sont des ressources
GET    /servers          → lister les serveurs
GET    /servers/42       → détail du serveur 42
POST   /servers          → créer un serveur
DELETE /servers/42       → supprimer le serveur 42

# ❌ Anti-pattern — des verbes dans les URLs
GET    /getServers
POST   /createServer
POST   /deleteServer/42

Commandes essentielles

Pourquoi FastAPI plutôt que Flask ou Django ? FastAPI offre la validation automatique des données (via Pydantic), une documentation Swagger auto-générée, et des performances comparables à Node.js grâce à l’async natif. Tu écris moins de code, tu obtiens plus de fonctionnalités.

Pour installer FastAPI et son serveur ASGI Uvicorn dans un environnement isolé :

mkdir fastapi-demo && cd fastapi-demo
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn[standard]

⚠️ Attention : Ne jamais pip install dans le Python système. Toujours utiliser un virtualenv. En prod, tu utiliseras un container Docker — mais en dev, le venv fait le job.

Maintenant, crée ton premier fichier main.py. Ce code définit une application FastAPI avec un endpoint racine qui renvoie du JSON :

from fastapi import FastAPI

app = FastAPI(
    title="Mon API Demo",
    description="API pour apprendre FastAPI",
    version="1.0.0"
)

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

@app.get("/health")
def health_check():
    return {"status": "healthy"}

Pour lancer le serveur en mode développement avec rechargement automatique :

uvicorn main:app --reload

• main → le fichier main.py
• app → l’instance FastAPI dans ce fichier
• --reload → recharge à chaque modification (dev uniquement, jamais en prod)

Pour tester tes endpoints, utilise curl ou ouvre ton navigateur :

# Tester l'endpoint racine
curl http://127.0.0.1:8000/

# Tester le health check
curl http://127.0.0.1:8000/health

# Route inexistante → 404 automatique
curl http://127.0.0.1:8000/nowhere
# {"detail":"Not Found"}

💡 Tip DevOps : FastAPI génère automatiquement une documentation Swagger sur /docs et ReDoc sur /redoc. Zéro configuration. Ouvre http://127.0.0.1:8000/docs — tu peux tester chaque endpoint directement depuis le navigateur.

Cas concret entreprise

Imagine que tu gères l’infra d’une startup SaaS. L’équipe dev vient de livrer un microservice de gestion de serveurs. Voici à quoi ressemble l’API que tu vas déployer et monitorer :

from fastapi import FastAPI, HTTPException

app = FastAPI(title="Infra API", version="1.0.0")

# Simuler une base de données en mémoire
servers_db = {
    1: {"name": "web-prod-01", "status": "active", "region": "eu-west"},
    2: {"name": "db-prod-01", "status": "active", "region": "eu-west"},
    3: {"name": "worker-staging", "status": "stopped", "region": "us-east"},
}

@app.get("/health")
def health():
    return {"status": "ok", "servers_count": len(servers_db)}

@app.get("/servers")
def list_servers(status: str = None):
    """Liste les serveurs, avec filtre optionnel par statut."""
    results = servers_db.values()
    if status:
        results = [s for s in results if s["status"] == status]
    return {"servers": list(results)}

@app.get("/servers/{server_id}")
def get_server(server_id: int):
    """Récupère un serveur par son ID."""
    if server_id not in servers_db:
        raise HTTPException(status_code=404, detail="Serveur introuvable")
    return servers_db[server_id]

🔥 Cas réel : Ce pattern /health + /servers + /servers/{id} est exactement ce que tu retrouves dans les APIs internes de boîtes comme Datadog, HashiCorp, ou GitLab. Le health check sert au load balancer (ALB, Traefik), les endpoints CRUD servent au dashboard interne. En prod, tu remplaces le dict par une vraie base de données — mais la structure de l’API reste identique.

Remarque le query parameter status sur /servers?status=active : FastAPI le détecte automatiquement depuis la signature de la fonction. Le path parameter server_id est typé int — si quelqu’un envoie /servers/abc, FastAPI renvoie un 422 Unprocessable Entity sans que tu écrives une seule ligne de validation.

Pièges fréquents

1. Oublier Uvicorn. FastAPI n’est pas un serveur — c’est un framework. Sans Uvicorn (ou Hypercorn), rien ne tourne. Si tu lances python main.py, il ne se passe rien.

2. Utiliser --reload en production. Le flag --reload surveille les fichiers et relance le process à chaque changement. En prod, ça signifie des micro-coupures aléatoires. Utilise uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 à la place.

3. Confondre path et query parameters. /servers/42 (path) identifie une ressource précise. /servers?status=active (query) filtre une collection. Mélanger les deux rend ton API incohérente.

4. Ignorer les codes HTTP. Renvoyer 200 avec {"error": "not found"} dans le body, c’est un anti-pattern classique. Utilise HTTPException(status_code=404) — tes outils de monitoring comptent sur les codes HTTP pour détecter les problèmes.

⚠️ Attention : En dev, FastAPI tourne sur 127.0.0.1 (localhost uniquement). Pour exposer sur le réseau (container Docker, VM), il faut --host 0.0.0.0. Sans ça, tes health checks depuis l’extérieur échouent systématiquement.

5. Ne pas versionner son API. Dès qu’un consommateur externe utilise ton API, toute modification cassante est un incident. Préfixe tes routes avec /v1/ dès le départ.

Exercice pratique

Crée une API de gestion d’inventaire avec trois endpoints :

# À toi de compléter ce squelette
from fastapi import FastAPI, HTTPException

app = FastAPI(title="Inventaire Infra")
inventory = {}
counter = 0

# POST /servers → ajoute un serveur (name, region, status)
# GET /servers → liste tous les serveurs
# GET /servers/{id} → détail d'un serveur (404 si inexistant)
# GET /health → retourne le nombre total de serveurs

# Bonus : ajoute un query parameter "region" sur GET /servers
# pour filtrer par région

Teste avec curl :

# Créer un serveur
curl -X POST http://localhost:8000/servers \
  -H "Content-Type: application/json" \
  -d '{"name": "web-01", "region": "eu-west", "status": "active"}'

# Lister les serveurs
curl http://localhost:8000/servers

# Filtrer par région
curl "http://localhost:8000/servers?region=eu-west"

🧠 À retenir : Pas besoin de tout coder de mémoire. L’important c’est de comprendre le pattern request → route → traitement → response. FastAPI s’occupe de la validation et de la doc — toi, tu te concentres sur la logique métier.

Ce qu’il faut retenir de ce chapitre :

• Une API est un contrat entre deux logiciels — requête structurée, réponse prévisible
• HTTP fournit les méthodes (GET, POST, PUT, DELETE) et les codes de statut (2xx, 4xx, 5xx)
• REST impose des conventions : URLs = ressources, méthodes HTTP = actions, sans état
• FastAPI = validation auto + doc Swagger + performances async — le meilleur ratio productivité/puissance en Python
• Toujours un /health, toujours un virtualenv, toujours les bons codes HTTP

➡️ La suite : Chapitre 2 — Routes et paramètres