Aller au contenu principal

Plan directeur

Repères utiles
remarque

Ce wiki est conçu comme un grand guide pédagogique en français pour apprendre à construire des APIs avec FastAPI de manière concrète, structurée et évolutive.

Pourquoi ce wiki existe​

Beaucoup de contenus sur FastAPI montrent soit :

  • de très petits exemples isolés,
  • soit du code sans vraie progression pédagogique,
  • soit des projets plus avancés mais difficiles à relier à une architecture simple.

Ce wiki vise à combler ce manque. Il doit permettre à un lecteur de voir comment une API se construit vraiment, depuis une base claire jusqu'à des enrichissements plus avancés.

Public visé​

Ce wiki vise surtout :

  • une personne qui connaît déjà un peu Python
  • une personne qui veut apprendre FastAPI sérieusement
  • une personne qui veut comprendre l'architecture d'une API, pas seulement recopier du code
  • une personne qui a besoin d'un guide pas à pas avec du code, des fichiers, des commandes et des vérifications

Ce que le wiki doit être​

Le wiki doit être :

  • progressif
  • concret
  • structuré
  • riche en explications
  • ancré dans du code réel
  • réutilisable comme base de référence

Ce que le wiki ne doit pas être​

Le wiki ne doit pas être :

  • une suite de notes superficielles
  • une simple paraphrase de documentation officielle
  • une liste de snippets sans architecture visible
  • une démonstration rapide qui laisse le lecteur sans cadre

Grande structure du wiki​

Le wiki est pensé autour de deux grands blocs.

Bloc 1 — API de base​

C'est la première grande section pratique du wiki.

Son rôle est de montrer comment construire une API FastAPI de base, avec une architecture claire, en s'appuyant sur le repo de référence task-organizer-API.

Cette section doit apprendre au lecteur :

  • comment organiser les dossiers
  • comment séparer routes, services, schémas et base de données
  • comment configurer l'application
  • comment brancher PostgreSQL
  • comment lancer l'API
  • comment tester les endpoints principaux

Bloc 2 — Advanced FastAPI​

Ce second bloc constitue, dans cette v1, la montée en puissance complète du socle construit dans API de base.

Son rôle n’est plus d’annoncer une roadmap en cours. Son rôle est maintenant de donner une vue d’ensemble stable sur les briques déjà rédigées :

Ce bloc couvre donc, dans la version actuelle :

  • sécurité et identité
  • ownership et relations SQL
  • robustesse et observabilité
  • testabilité
  • packaging et exécution reproductible
  • communication utilisateur
  • exécution asynchrone
  • bonus frontend

Choix pédagogique central​

Le lecteur doit d'abord construire quelque chose de simple, cohérent et complet avant d'empiler des fonctionnalités avancées.

Donc le socle de ce wiki est :

  1. construire une API de base saine
  2. comprendre son architecture
  3. seulement ensuite ajouter des briques supplémentaires

Standard de qualité attendu​

Chaque gros chapitre pratique doit :

  • montrer une arborescence de projet
  • montrer les fichiers importants
  • inclure du code commenté ou expliqué pédagogiquement
  • relier le code à l'architecture
  • montrer les commandes utiles
  • montrer comment tester ce qui a été construit
  • expliciter les erreurs fréquentes

Stratégie d'itération​

Le wiki a été construit en trois temps :

  1. mise en place du socle avec les notes de pilotage et API de base
  2. extension structurée avec Advanced FastAPI et ses sous-chapitres concrets
  3. raffinement transversal avec Parcours de lecture, FAQ, erreurs fréquentes et conseils pratiques et plusieurs passes de polish éditorial

La logique d’itération n’est donc plus ouverte sur des manques immédiats. Pour cette v1, la structure voulue est maintenant en place.

Référence de base pour le premier chapitre​

Le chapitre API de base s'appuie sur :

  • le repo GitHub EnesBrt/task-organizer-API
  • son architecture générale : main.py, config.py, api/, database/, services/
  • son intention pédagogique : montrer une API de gestion de tâches simple mais proprement organisée

Le wiki n'a pas pour mission de recopier le repo sans recul. Il a pour mission de transformer cette architecture en tutoriel guidé.

Décision structurante​

La première grande section pratique du wiki s’appelle officiellement :

API de base

Et cette section devait impérativement contenir :

  • du code
  • des explications
  • une progression pas à pas
  • une vérification guidée

Cette décision a été conservée jusqu’au bout et structure encore toute la lecture du wiki.

Statut actuel de la v1​

À ce stade, la version 1 du wiki est considérée comme complète. Elle comprend :

Limites assumées et suites possibles​

Cette v1 reste volontairement ciblée :

  • pas de glossaire séparé
  • pas de dossier comparatif
  • pas de dossier de sources
  • pas de couche de fondations séparée tant qu’elle n’apporte pas une vraie valeur pédagogique supplémentaire

Des suites sont toujours possibles après la v1, mais elles relèvent d’un enrichissement optionnel, pas d’un manque bloquant :

  • nouvelles fondations si un besoin réel apparaît
  • approfondissements thématiques
  • nouveaux cas d’usage si le périmètre du wiki s’élargit
  • nouvelle passe éditoriale seulement si l’on veut dépasser la v1, pas pour la rendre simplement utilisable