L'API des étudiants — CRUD complet : POST, GET, PUT et DELETE sur la base de données

Qu’allons-nous apprendre ?#

Nous complétons l’API selon le tableau de correspondance :

• POST /students → INSERT → 201.
• PUT /students/{id} → UPDATE → 200 / 404 / 409.
• DELETE /students/{id} → DELETE → 204 / 404.
• Un modèle d’entrée (Pydantic) et une validation métier partagée (400).

Pourquoi en avons-nous besoin ?#

C’est le court projet qui résume serveur + base de données + CRUD, comme le définit le programme. À la fin de la leçon, il y a une vraie API : une application, un frontend ou un autre service peut créer, lire, mettre à jour et supprimer des étudiants, et les données sont enregistrées dans la base.

Explication à partir des bases#

Le modèle d’entrée#

class StudentIn(BaseModel):
    name: str
    age: int
    email: str

StudentIn décrit ce que le client envoie dans un POST et dans un PUT. Il n’y a pas d’id dedans, car l’id est donné par la base (POST) ou par le chemin (PUT). Le nom ...In est une convention courante : « le modèle de ce qui entre ».

FastAPI valide la structure et les types (un champ manquant, du texte au lieu d’un nombre → 422, automatiquement).

La validation métier — 400#

Les règles (âge 16–120, un nom d’au moins 2 caractères, un e-mail avec @) sont les nôtres. Vérifiez-les dans une seule fonction, que POST et PUT appellent (DRY) :

def validate_student(student):
    if student.age < 16 or student.age > 120:
        raise HTTPException(status_code=400, detail="age must be between 16 and 120")

Trois couches de vérifications, chacune avec son rôle :

204 No Content#

Pour un DELETE réussi, il n’y a rien à renvoyer : l’étudiant a été supprimé. status_code=204 dit « j’ai réussi, sans corps ». La fonction ne renvoie simplement rien (None), et FastAPI envoie une réponse vide.

Traduire une ValueError#

try:
    return db.create_student(...)
except ValueError as error:
    raise HTTPException(status_code=409, detail=str(error))

str(error) = le message qu’a écrit db.py (« a student with email … already exists »). Le message traverse deux couches : de la base (IntegrityError), via db.py (ValueError), jusqu’au client (409 + detail).

Syntaxe#

@app.post("/students", status_code=201)
def create_student(student: StudentIn):            # body
    ...

@app.put("/students/{student_id}")
def update_student(student_id: int, student: StudentIn):   # path + body together
    ...

@app.delete("/students/{student_id}", status_code=204)
def delete_student(student_id: int):
    ...                                            # return nothing on success

Dans PUT, il y a à la fois un Path Parameter et un body. FastAPI les distingue : student_id dans le chemin, et student (un modèle) dans le body.

Premier exemple de code#

Le main.py complet :

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

import db

app = FastAPI(title="Students API")
db.init_db()

class StudentIn(BaseModel):
    name: str
    age: int
    email: str

def validate_student(student):
    if len(student.name.strip()) < 2:
        raise HTTPException(status_code=400, detail="name must have at least 2 characters")
    if student.age < 16 or student.age > 120:
        raise HTTPException(status_code=400, detail="age must be between 16 and 120")
    if "@" not in student.email:
        raise HTTPException(status_code=400, detail="invalid email")

@app.get("/students")
def list_students():
    return db.get_all_students()

@app.get("/students/{student_id}")
def get_student(student_id: int):
    student = db.get_student(student_id)
    if student is None:
        raise HTTPException(status_code=404, detail="student not found")
    return student

@app.post("/students", status_code=201)
def create_student(student: StudentIn):
    validate_student(student)
    try:
        return db.create_student(student.name, student.age, student.email)
    except ValueError as error:
        raise HTTPException(status_code=409, detail=str(error))

@app.put("/students/{student_id}")
def update_student(student_id: int, student: StudentIn):
    validate_student(student)
    try:
        updated = db.update_student(student_id, student.name, student.age, student.email)
    except ValueError as error:
        raise HTTPException(status_code=409, detail=str(error))
    if updated is None:
        raise HTTPException(status_code=404, detail="student not found")
    return updated

@app.delete("/students/{student_id}", status_code=204)
def delete_student(student_id: int):
    if not db.delete_student(student_id):
        raise HTTPException(status_code=404, detail="student not found")

Le lancement : uvicorn main:app --reload, depuis le dossier du projet, avec le venv actif.

Analyse du code ligne par ligne#

Au total : un fichier d’environ 60 lignes, qui contient une API complète. Chaque route est courte, car tout le travail lourd (SQL, contraintes) est dans db.py, et toutes les conversions (JSON, types) sont dans FastAPI.

Un autre exemple#

Toutes les vraies réponses du serveur — une suite de requêtes sur une base vide (testée avec le code ci-dessus) :

Et le journal du serveur (dans le terminal d’uvicorn) affiche une ligne pour chaque requête, par exemple :

INFO:     127.0.0.1:49197 - "POST /students HTTP/1.1" 201 Created
INFO:     127.0.0.1:49198 - "GET /students/999 HTTP/1.1" 404 Not Found

Bien lire le tableau : chacune des lignes a une raison dans une couche différente :

• 422 (lignes 5, 6, 9) — FastAPI et Pydantic. Notre code ne s’est pas exécuté.
• 400 (ligne 4) — validate_student.
• 409 (ligne 3) — la base (UNIQUE), via db.py.
• 404 (lignes 8, 11, 13) — db.py a renvoyé None/False.

Erreur courante#

Erreur 1 : oublier status_code=201 dans POST, ou 204 dans DELETE. Tout « fonctionne », mais avec 200. Le client (et les tests automatisés) attend les bons codes.

Erreur 2 : renvoyer du contenu depuis un DELETE avec 204.

@app.delete("/students/{student_id}", status_code=204)
def delete_student(student_id: int):
    db.delete_student(student_id)
    return {"message": "deleted"}

Selon la norme HTTP, un 204 ne doit pas avoir de corps. Différentes versions de FastAPI gèrent cela différemment (une erreur, ou un corps jeté). Soit 204 sans return, soit 200 avec un message. Pas les deux.

Erreur 3 : oublier la vérification de None dans PUT. return db.update_student(...) renvoie 200 avec null pour un étudiant qui n’existe pas.

Erreur 4 : except Exception dans une route.

try:
    return db.create_student(...)
except Exception:
    raise HTTPException(status_code=409, detail="conflict")

Un vrai bug (par exemple une table manquante) sera renvoyé comme « 409 Conflict », et induira tout le monde en erreur. N’attrapez que ValueError, et tout le reste arrivera en 500, pour que nous le voyions et le corrigions.

Erreur 5 : une validation dupliquée et différente. Une vérification de l’âge dans POST « plus de 16 », et dans PUT « plus de 18 ». Une seule fonction (validate_student).

Exercices#

Les exercices n’utilisent que ce qui a été vu dans cette leçon et les précédentes. Essayez d’abord seul, et n’ouvrez la solution qu’ensuite.

Exercice 1: POST — créer#

Ajoutez à main.py un modèle StudentIn (name, age, email) et un POST /students qui renvoie 201. Un e-mail en double (une ValueError de db.create_student) → 409.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

import db

app = FastAPI(title="Students API")
db.init_db()


class StudentIn(BaseModel):
    name: str
    age: int
    email: str


@app.post("/students", status_code=201)
def create_student(student: StudentIn):
    try:
        return db.create_student(student.name, student.age, student.email)
    except ValueError as error:
        raise HTTPException(status_code=409, detail=str(error))

Exercice 2: Les règles de validation#

Écrivez validate_student(student) qui lance une HTTPException avec 400 si : le nom fait moins de 2 caractères, l’âge est en dehors de 16 à 120, ou il n’y a pas de @ dans l’e-mail. Exécutez-la dans POST avant d’enregistrer.

MIN_NAME_LENGTH = 2
MIN_AGE = 16
MAX_AGE = 120


def validate_student(student):
    if len(student.name.strip()) < MIN_NAME_LENGTH:
        raise HTTPException(status_code=400, detail="name too short")
    if student.age < MIN_AGE or student.age > MAX_AGE:
        raise HTTPException(status_code=400, detail="age must be 16-120")
    if "@" not in student.email:
        raise HTTPException(status_code=400, detail="invalid email")


@app.post("/students", status_code=201)
def create_student(student: StudentIn):
    validate_student(student)
    try:
        return db.create_student(student.name, student.age, student.email)
    except ValueError as error:
        raise HTTPException(status_code=409, detail=str(error))

Exercice 3: PUT — mettre à jour#

Ajoutez PUT /students/{student_id} : validation (400), un étudiant qui n’existe pas (404), un e-mail pris par un autre étudiant (409), et sinon 200 avec l’étudiant mis à jour.

@app.put("/students/{student_id}")
def update_student(student_id: int, student: StudentIn):
    validate_student(student)
    try:
        updated = db.update_student(student_id, student.name, student.age, student.email)
    except ValueError as error:
        raise HTTPException(status_code=409, detail=str(error))
    if updated is None:
        raise HTTPException(status_code=404, detail="student not found")
    return updated

Exercice 4: DELETE — 204#

Ajoutez DELETE /students/{student_id} qui renvoie 204 quand la suppression a réussi, et 404 quand il n’y a pas de tel étudiant. Pourquoi ne renvoie-t-on pas de corps avec 204 ?

@app.delete("/students/{student_id}", status_code=204)
def delete_student(student_id: int):
    if not db.delete_student(student_id):
        raise HTTPException(status_code=404, detail="student not found")

Exercice 5: Qui décide de quel code ?#

Pour chaque requête — quel code reviendra, et qui le renvoie : Pydantic, notre code (validate_student), ou la traduction depuis db ?

1. POST /students   {"name": "Noa", "age": "abc", "email": "noa@mail.com"}
2. POST /students   {"name": "Noa", "age": 10, "email": "noa@mail.com"}
3. POST /students   {"name": "Noa", "age": 22, "email": "dana@mail.com"}   (taken)
4. PUT  /students/99  {"name": "Noa", "age": 22, "email": "noa@mail.com"}
5. DELETE /students/1   (exists)

Résumé#

• POST → db.create_student → 201 + l’étudiant. Une ValueError → 409.
• PUT (chemin + body) → db.update_student → 200. None → 404. Une ValueError → 409.
• DELETE → db.delete_student → 204 sans corps. False → 404.
• Trois couches de vérifications : 422 (Pydantic, la structure), 400 (validate_student, les règles), 409 (la base, l’unicité).
• La validation dans une seule fonction pour POST et PUT. N’attrapez que ValueError, et tout le reste reste un 500.
• Un main.py d’environ 60 lignes = une API complète, car chaque couche fait son propre travail.

Documentation officielle#

• FastAPI — Request Body
• FastAPI — Response Status Code
• FastAPI — Body - Updates