Lernzettel: Fondamentaux de FastAPI

📋 Plan du Cours

1. Présentation et choix de FastAPI
2. Projet et prérequis du cours
3. Création d’une première application
4. Exécution et documentation automatique
5. Paramètres et validation des données
6. Débogage et gestion des erreurs
7. Fonctions synchrones et asynchrones
8. Données automobiles et filtrage
9. Paramètres de requête et de chemin
10. Modèles Pydantic et validation
11. Chargement et sauvegarde JSON
12. Méthodes HTTP REST
13. Schémas d’entrée et de sortie
14. Opérations et données imbriquées

📖 1. Présentation et choix de FastAPI

🔑 Notions clés & Définitions

• FastAPI : Un framework web moderne et performant destiné à construire des API à partir des annotations de type standard de Python.

★ À maîtriser

• FastAPI utilise fortement les annotations de type pour valider et convertir automatiquement les données, générer la documentation des opérations et produire du code concis et performant.

📌 Django est un framework mature et complet principalement conçu pour les sites web, tandis que Flask est un microframework fournissant très peu de fonctionnalités sans extensions.

Compléments

📌 FastAPI est un choix adapté pour créer uniquement une API REST, tandis que Django avec django-rest-framework convient mieux lorsqu’une API fait partie d’un site web complet.

📖 2. Projet et prérequis du cours

★ À maîtriser

• Le projet du cours construit une API REST pour une application d’autopartage permettant notamment de créer, modifier et supprimer des voitures et d’ajouter des trajets.

📌 Pour suivre le cours, il faut connaître les bases de Python, notamment les fonctions, les classes, les dictionnaires et les listes, ainsi que les notions essentielles de HTTP, des API REST et des bases relationnelles.

Compléments

• Les données du projet sont stockées dans une base de données au moyen de modèles écrits avec la bibliothèque SQLModel.

• Le cours aborde OAuth, le service de pages HTML, le traitement des formulaires HTML, les cookies, les en-têtes, le middleware, les tests unitaires et le déploiement.

• FastAPI ne prend pas en charge les versions de Python antérieures à 3.8 et le travail pratique nécessite un éditeur de code tel que PyCharm ou Visual Studio Code.

📖 3. Création d’une première application

🔑 Notions clés & Définitions

• Objet FastAPI : L’objet créé par l’appel au constructeur FastAPI représente l’application ou le serveur REST construit par le projet.
• Opération de chemin : Une fonction associée à une URL et à une méthode HTTP au moyen d’un décorateur tel que @app.get.

📝 Points essentiels

• La création d’un projet FastAPI consiste à créer un environnement virtuel, installer FastAPI avec ses dépendances, créer un fichier Python et instancier un objet FastAPI dans ce fichier.

• L’installation complète s’effectue avec la commande $python\ -m\ pip\ install\ "fastapi[all]"$.

📖 4. Exécution et documentation automatique

★ À maîtriser

• Le lancement en développement s’effectue avec la commande $fastapi\ dev\ carsharing.py$, qui recharge automatiquement l’application lorsque le code change.

📌 En production, il faut utiliser $fastapi\ run\ carsharing.py$ plutôt que le mode dev, notamment pour des raisons de sécurité et de performance.

• FastAPI ajoute automatiquement la documentation interactive à l’URL /docs, une autre présentation à /redoc et la spécification OpenAPI lisible par machine à /openapi.json.

• Lorsqu’une requête HTTP arrive, Uvicorn la reçoit, FastAPI recherche l’opération associée au chemin et à la méthode, exécute la fonction puis renvoie sa valeur au client.

Compléments

• La page /docs permet d’exécuter une opération avec « Try it out », et l’opération d’accueil renvoie actuellement le statut HTTP 200 lorsque son exécution réussit.

📖 5. Paramètres et validation des données

🔑 Notions clés & Définitions

• Paramètre de requête : Une valeur transmise dans l’URL après un point d’interrogation, par exemple name dans /?name=reindart.
• Paramètre de chemin : Une valeur intégrée à l’URL entre accolades dans le décorateur, par exemple {id} dans /api/cars/{id}.

★ À maîtriser

• Les paramètres de requête sont obligatoires par défaut, mais une valeur par défaut comme None permet de les rendre optionnels.

• FastAPI utilise les annotations de type pour convertir les valeurs textuelles reçues dans l’URL vers le type attendu et vérifier que la conversion est valide.

Compléments

• Lorsqu’un paramètre optionnel peut être une chaîne ou None, son annotation peut utiliser l’opérateur pipe, comme str | None, et un paramètre entier optionnel peut utiliser int | None.

• Les annotations de type des paramètres sont également visibles dans la documentation générée et dans la spécification openapi.json.

💡 Astuce mémo

Query après ?, path dans l’URL

📖 6. Débogage et gestion des erreurs

📝 Points essentiels

• Dans PyCharm ou Visual Studio Code, un point d’arrêt suspend l’exécution sur une ligne afin d’inspecter les variables, puis Step Over exécute une seule ligne avant de suspendre à nouveau.

• Sans annotation int, l’identifiant reçu depuis l’URL est une chaîne, tandis que les identifiants stockés dans les données automobiles sont des entiers, ce qui rend la comparaison toujours fausse.

📖 7. Fonctions synchrones et asynchrones

★ À maîtriser

📌 Une opération de chemin doit être déclarée avec async def lorsqu’elle utilise une bibliothèque tierce dont les appels nécessitent await.

📌 Une opération utilisant une bibliothèque de communication sans support asynchrone, comme SQLModel dans le cours, doit généralement être déclarée avec def.

Compléments

📌 Si l’on ne sait pas quelle forme choisir, il est recommandé d’utiliser une fonction normale avec def, et FastAPI peut mélanger des fonctions def et async def dans une même application.

💡 Astuce mémo

await implique async, sinon def

📖 8. Données automobiles et filtrage

📝 Points essentiels

• Les premières données automobiles sont simulées par une liste de dictionnaires, chaque dictionnaire représentant une voiture avec notamment sa taille, son type d’énergie, son nombre de portes et sa transmission.

• L’opération GET /api/cars renvoie l’ensemble des voitures disponibles dans la liste de données.

• Le filtrage des voitures commence avec toute la liste, applique le filtre de taille s, m ou l lorsqu’il est fourni, puis applique éventuellement le filtre du nombre de portes.

• Les valeurs reçues depuis une URL sont textuelles, même lorsqu’elles représentent un nombre, ce qui nécessite une annotation int pour comparer correctement le nombre de portes ou l’identifiant d’une voiture.

📖 9. Paramètres de requête et de chemin

★ À maîtriser

• Un paramètre de requête est généralement obligatoire mais peut devenir optionnel grâce à une valeur par défaut, tandis qu’un paramètre de chemin ne peut pas être optionnel car il fait partie du motif de l’URL.

• Pour une requête vers /api/cars/5, FastAPI recherche le motif correspondant, extrait la valeur 5 de l’URL et la transmet au paramètre de chemin id après conversion et validation selon son annotation de type.

📌 Lorsqu’une voiture correspondant à l’identifiant demandé n’existe pas, l’opération doit lever une HTTPException avec le statut 404 et peut fournir un message détaillé.

Compléments

• Pour autoriser une valeur absente en Python 3.10 ou plus récent, un champ peut être typé comme une union, par exemple $size : str \mid None$ ou $doors : int \mid None$, avec une valeur par défaut de None.

📖 10. Modèles Pydantic et validation

🔑 Notions clés & Définitions

• Modèle Pydantic : Une classe qui hérite de BaseModel et dont les attributs déclarent les champs, les types et les valeurs par défaut d’une structure de données valide.

★ À maîtriser

📌 Un champ Pydantic est obligatoire lorsqu’il n’a pas de valeur par défaut, tandis qu’une valeur par défaut le rend facultatif lors de la construction de l’objet.

• Pydantic convertit automatiquement une valeur vers le type déclaré lorsqu’une conversion est possible, par exemple les chaînes représentant des nombres vers des entiers, et produit une erreur de validation si la conversion échoue.

Compléments

• La création d’un objet Pydantic à partir d’arguments nommés fournit automatiquement un constructeur, vérifie les champs obligatoires et prépare un objet imprimable.

• Les modèles Pydantic peuvent fournir des utilitaires pour convertir les objets en JSON, en dictionnaires ou en chaînes, en plus de leur construction et validation.

📖 11. Chargement et sauvegarde JSON

★ À maîtriser

• La fonction load_db ouvre cars.json, charge une liste de dictionnaires avec json.load, puis transforme chaque dictionnaire en objet Car grâce à Car.model_validate.

• La fonction save_db ouvre cars.json en écriture, convertit chaque objet en dictionnaire, puis écrit la liste avec json.dump et indent=4 pour obtenir un fichier lisible.

Compléments

📌 Un fichier JSON doit utiliser des chaînes entre guillemets doubles et ne doit pas contenir de virgule finale, même si les chaînes entre guillemets simples et certaines virgules finales sont acceptées en Python.

• Le stockage direct des objets dans un fichier JSON constitue une simulation simple de base de données et n’est pas considéré comme une solution fiable pour la production.

• Au démarrage de l’application, l’appel à load_db après son import recharge les voitures du fichier JSON dans la structure utilisée par FastAPI.

💡 Astuce mémo

JSON → dictionnaires → objets ; objets → dictionnaires → JSON

📖 12. Méthodes HTTP REST

📝 Points essentiels

• GET sert à récupérer une ressource sans effet de bord, POST sert généralement à créer une ressource dans une collection, PUT sert à modifier une ressource identifiée et DELETE sert à la supprimer.

• Pour créer une voiture avec POST, le client envoie les données dans le corps de la requête vers l’URL de la collection /api/cars, et la ressource reçoit ensuite sa propre URL.

• Pour modifier une voiture avec PUT, le client utilise l’URL de cette voiture avec son identifiant et envoie les nouvelles données dans le corps de la requête.

• Une suppression réussie peut renvoyer le statut 204 No Content avec un corps vide, tandis qu’une voiture inexistante entraîne une HTTPException de statut 404.

📖 13. Schémas d’entrée et de sortie

★ À maîtriser

• Un modèle d’entrée décrit les données que le client peut envoyer, tandis qu’un modèle de sortie décrit les données que l’API renvoie au client.

• CarOutput hérite de CarInput et ajoute le champ id, de sorte que CarInput représente une voiture sans identifiant fourni par le client et CarOutput une voiture enregistrée avec identifiant.

• Dans l’opération POST de création, FastAPI construit un objet CarInput depuis le corps JSON, puis l’application crée un CarOutput avec un nouvel identifiant, l’enregistre et le renvoie.

• L’utilisation d’un modèle Pydantic comme argument d’opération indique à FastAPI de lire cet objet dans le corps de la requête et d’en valider la structure avant d’appeler la fonction.

Compléments

• Des modèles d’entrée et de sortie distincts évitent d’exposer accidentellement des champs stockés en base mais qui ne doivent pas être transmis, comme des informations sensibles.

💡 Astuce mémo

Input sans identifiant, Output avec identifiant

📖 14. Opérations et données imbriquées

★ À maîtriser

• Une opération DELETE recherche la voiture par identifiant, la retire de la base si elle existe, sauvegarde les données et renvoie généralement le statut 204 sans contenu.

• Une opération PUT reçoit l’identifiant depuis le chemin et les nouvelles propriétés depuis le corps, remplace les champs de la voiture trouvée sans modifier son identifiant, sauvegarde puis renvoie l’objet mis à jour.

• Un modèle Pydantic peut contenir une liste d’un autre modèle, comme une voiture contenant une liste de trajets, et FastAPI sérialise automatiquement cette structure imbriquée dans les requêtes et réponses.

Compléments

• Postman peut importer le fichier openapi.json généré par FastAPI et reconnaître automatiquement les opérations GET, POST, PUT et DELETE ainsi que leurs paramètres et corps de requête.

• Pour ajouter un trajet à une voiture, l’API reçoit l’identifiant de la voiture en paramètre de requête et les données du trajet dans le corps, crée le trajet avec un identifiant, l’ajoute à la liste, sauvegarde et renvoie le trajet créé.

📊 Tableaux de synthèse

Comparaison des frameworks Python

Framework	Orientation	Atouts et limites
FastAPI	API REST	Annotations de type, validation, conversion, documentation automatique et hautes performances
Django	Sites web complets	Framework mature et riche, mais ses fonctionnalités supplémentaires aident moins directement à créer une API
Flask	Petits projets web	Microframework minimal nécessitant souvent du code ou des extensions supplémentaires pour les API REST

Méthodes HTTP du service

Méthode	Cible	Rôle	Réponse typique
GET	Ressource ou collection	Lire sans modifier	Données de la ressource
POST	Collection	Créer une ressource	Ressource créée
PUT	Ressource identifiée	Modifier une ressource	Ressource mise à jour
DELETE	Ressource identifiée	Supprimer une ressource	204 No Content