FastAPI Endpoint

Overview

Pattern pour créer des endpoints REST avec FastAPI, incluant la validation des paramètres via Query, les modèles de réponse Pydantic, et les templates Jinja2.

File Structure

code

src/cuve-api/
├── app/
│   ├── main.py          # Application FastAPI + endpoints
│   ├── templates/       # Templates Jinja2
│   │   └── index.html

Implementation Pattern

Définition de l'application

python

from fastapi import FastAPI, Query
from fastapi.responses import HTMLResponse
from fastapi.requests import Request
from fastapi.templating import Jinja2Templates
from pydantic import BaseModel

app = FastAPI(title="Cuve API", version="0.3.0")
templates = Jinja2Templates(directory="app/templates")

Modèles Pydantic avec exemples

python

class LastResponse(BaseModel):
    has_data: bool
    distance_cm: Optional[int] = None
    volume_liters: Optional[float] = None
    fill_percent: Optional[float] = None

    class Config:
        json_schema_extra = {
            "example": {
                "has_data": True,
                "distance_cm": 48,
                "volume_liters": 7420.5,
                "fill_percent": 74.2,
            }
        }

Endpoint avec Query parameters

python

@app.get("/api/extremes", response_model=ExtremesResponse)
async def api_extremes(
        period: Period = Query("day"),
        order: Order = Query("max"),
        n: int = Query(5, ge=1, le=50),
):
    rows = cuve_db.get_extremes(settings.db_path, period=period, n=n, order=order)
    return {"period": period, "order": order, "count": len(rows), "items": rows}

Endpoint HTML avec template

python

@app.get("/", response_class=HTMLResponse)
async def index(request: Request):
    version = time.strftime("%d.%m.%Y %Hh%M")
    return templates.TemplateResponse("index.html", {"request": request, "version": version})

Lifecycle events (startup/shutdown)

python

@app.on_event("startup")
async def on_startup():
    global _collect_task
    _collect_task = asyncio.create_task(collector_loop())

@app.on_event("shutdown")
async def on_shutdown():
    if _collect_task:
        _collect_task.cancel()

Rules

Do

•Utiliser response_model pour documenter et valider les réponses
•Ajouter json_schema_extra avec des exemples réalistes
•Utiliser Query() avec ge, le pour valider les paramètres numériques
•Utiliser des Literal types pour les énumérations (ex: Period, Order)
•Préfixer les routes API par /api/
•Utiliser async def pour tous les endpoints

Don't

•Ne pas mélanger logique métier et définition d'endpoint
•Ne pas oublier le request dans le contexte des templates
•Ne pas utiliser des chemins relatifs pour les templates

File Location

•Application principale : src/cuve-api/app/main.py
•Templates HTML : src/cuve-api/app/templates/