Référence API

Toutes les routes sont préfixées par /api/v1 (app.setGlobalPrefix('api/v1') dans apps/api/src/main.ts). L'authentification se fait par JWT (header Authorization: Bearer <token>) avec rotation des refresh tokens. La validation des payloads est faite côté backend par les schémas Zod du package @app/contracts (packages/contracts/src/).

Conventions

• Auth: public — aucun token requis
• Auth: JWT — token JWT valide requis (n'importe quel rôle)
• Auth: ADMIN / TEACHER / LEARNER — rôle spécifique requis (RBAC via @Roles)
• Les schémas référencés (createCourseInputSchema, etc.) sont définis dans packages/contracts/src/<domaine>.ts et exportés via packages/contracts/src/index.ts.
• Les chemins listés dans les tableaux sont relatifs au préfixe /api/v1 (ex. /auth/login = /api/v1/auth/login).
• Les paramètres :id sont validés par ParseUUIDPipe ; les payloads JSON le sont par ZodValidationPipe (généré via nestjs-zod) ou directement par ZodValidationPipe pour les unions discriminées.

Santé (/health)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/health	public	Endpoint de liveness/health-check (uptime, statut DB).	—	{ status, ... } (ad hoc)

Authentification & profil (/auth)

Méthode	Chemin	Auth	Description	Input schema	Output schema
POST	/auth/register	public	Inscription d'une apprenante (rôle LEARNER ou TEACHER).	registerInputSchema	authResponseSchema
POST	/auth/login	public	Connexion par identifiant (email ou username) + mot de passe.	loginInputSchema	authResponseSchema
POST	/auth/refresh	public	Échange un refresh token contre une nouvelle paire (rotation).	refreshInputSchema	authResponseSchema
POST	/auth/logout	public	Révoque le refresh token fourni (204).	refreshInputSchema	—
GET	/auth/me	JWT	Retourne le user courant depuis la DB (données fraîches).	—	userPublicSchema
PATCH	/auth/me	JWT	Met à jour le profil du user connecté (name, email, bio…).	updateMeInputSchema	userPublicSchema
POST	/auth/me/avatar	JWT	Upload avatar (multipart file, max 2 Mo, png/jpeg/webp).	multipart/form-data	avatarUploadResponseSchema
DELETE	/auth/me/avatar	JWT	Supprime l'avatar courant (204).	—	—
POST	/auth/change-password	JWT	Change le mot de passe et révoque toutes les sessions (204).	changePasswordInputSchema	—
GET	/auth/admin-ping	ADMIN	Endpoint témoin RBAC (à supprimer en v1.1).	—	{ status, pingedBy, role, at }

Catalogue public (/courses)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/courses	public	Liste paginée du catalogue (query : page, pageSize, q).	query params	coursesListPublicSchema
GET	/courses/:slug	public	Détail complet d'un cours par slug (modules → sections → blocs).	—	courseDetailPublicSchema

Création de cours — espace teacher (/teacher/courses)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/courses	TEACHER, ADMIN	Liste les cours créés par la teacher (ADMIN voit tout).	—	coursePublicSchema[]
POST	/teacher/courses	TEACHER, ADMIN	Crée un nouveau cours (slug auto-généré).	createCourseInputSchema	coursePublicSchema
GET	/teacher/courses/:id	TEACHER, ADMIN	Détail d'un cours (ownership vérifiée).	—	coursePublicSchema
PATCH	/teacher/courses/:id	TEACHER, ADMIN	Met à jour un cours.	updateCourseInputSchema	coursePublicSchema
POST	/teacher/courses/:id/publish	TEACHER, ADMIN	Passe le cours en PUBLISHED.	—	coursePublicSchema
POST	/teacher/courses/:id/archive	TEACHER, ADMIN	Passe le cours en ARCHIVED.	—	coursePublicSchema
DELETE	/teacher/courses/:id	TEACHER, ADMIN	Soft delete (204).	—	—

Modules teacher (/teacher/modules, /teacher/courses/:courseId/modules)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/courses/:courseId/modules	TEACHER, ADMIN	Liste les modules d'un cours.	—	modulePublicSchema[]
POST	/teacher/courses/:courseId/modules	TEACHER, ADMIN	Crée un module sous le cours.	createModuleInputSchema	modulePublicSchema
PATCH	/teacher/courses/:courseId/modules/reorder	TEACHER, ADMIN	Réordonne les modules du cours.	reorderInputSchema	modulePublicSchema[]
GET	/teacher/modules/:id	TEACHER, ADMIN	Détail d'un module.	—	modulePublicSchema
PATCH	/teacher/modules/:id	TEACHER, ADMIN	Met à jour un module.	updateModuleInputSchema	modulePublicSchema
POST	/teacher/modules/:id/publish	TEACHER, ADMIN	Publie le module.	—	modulePublicSchema
POST	/teacher/modules/:id/unpublish	TEACHER, ADMIN	Repasse le module en DRAFT.	—	modulePublicSchema
DELETE	/teacher/modules/:id	TEACHER, ADMIN	Soft delete (204).	—	—

Chapitres teacher (/teacher/chapters, /teacher/modules/:moduleId/chapters)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/modules/:moduleId/chapters	TEACHER, ADMIN	Liste les chapitres d'un module.	—	chapterPublicSchema[]
POST	/teacher/modules/:moduleId/chapters	TEACHER, ADMIN	Crée un chapitre sous le module.	createChapterInputSchema	chapterPublicSchema
PATCH	/teacher/modules/:moduleId/chapters/reorder	TEACHER, ADMIN	Réordonne les chapitres.	reorderInputSchema	chapterPublicSchema[]
GET	/teacher/chapters/:id	TEACHER, ADMIN	Détail d'un chapitre.	—	chapterPublicSchema
PATCH	/teacher/chapters/:id	TEACHER, ADMIN	Met à jour un chapitre.	updateChapterInputSchema	chapterPublicSchema
POST	/teacher/chapters/:id/publish	TEACHER, ADMIN	Publie le chapitre.	—	chapterPublicSchema
POST	/teacher/chapters/:id/unpublish	TEACHER, ADMIN	Repasse le chapitre en DRAFT.	—	chapterPublicSchema
DELETE	/teacher/chapters/:id	TEACHER, ADMIN	Soft delete (204).	—	—

Sections teacher (/teacher/sections, /teacher/chapters/:chapterId/sections)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/chapters/:chapterId/sections	TEACHER, ADMIN	Liste les sections d'un chapitre.	—	sectionPublicSchema[]
POST	/teacher/chapters/:chapterId/sections	TEACHER, ADMIN	Crée une section.	createSectionInputSchema	sectionPublicSchema
PATCH	/teacher/chapters/:chapterId/sections/reorder	TEACHER, ADMIN	Réordonne les sections.	reorderInputSchema	sectionPublicSchema[]
GET	/teacher/sections/:id	TEACHER, ADMIN	Détail d'une section.	—	sectionPublicSchema
PATCH	/teacher/sections/:id	TEACHER, ADMIN	Met à jour une section.	updateSectionInputSchema	sectionPublicSchema
POST	/teacher/sections/:id/publish	TEACHER, ADMIN	Publie la section.	—	sectionPublicSchema
POST	/teacher/sections/:id/unpublish	TEACHER, ADMIN	Repasse la section en DRAFT.	—	sectionPublicSchema
DELETE	/teacher/sections/:id	TEACHER, ADMIN	Soft delete (204).	—	—

Blocs de contenu teacher (/teacher/blocks, /teacher/sections/:sectionId/blocks)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/sections/:sectionId/blocks	TEACHER, ADMIN	Liste les blocs d'une section.	—	contentBlockPublicSchema[]
POST	/teacher/sections/:sectionId/blocks	TEACHER, ADMIN	Crée un bloc (TEXT, IMAGE, VIDEO, YOUTUBE).	contentBlockInputSchema	contentBlockPublicSchema
PATCH	/teacher/sections/:sectionId/blocks/reorder	TEACHER, ADMIN	Réordonne les blocs.	reorderInputSchema	contentBlockPublicSchema[]
PATCH	/teacher/blocks/:id	TEACHER, ADMIN	Remplace un bloc (type + data).	contentBlockInputSchema	contentBlockPublicSchema
DELETE	/teacher/blocks/:id	TEACHER, ADMIN	Supprime un bloc (204).	—	—

Quiz teacher (/teacher/quizzes, /teacher/chapters/:chapterId/quiz, /teacher/questions)

Méthode	Chemin	Auth	Description	Input schema	Output schema
POST	/teacher/chapters/:chapterId/quiz	TEACHER, ADMIN	Crée le quiz du chapitre (1:1).	createQuizInputSchema	quizPublicSchema
GET	/teacher/chapters/:chapterId/quiz	TEACHER, ADMIN	Récupère le quiz du chapitre.	—	quizPublicSchema
GET	/teacher/quizzes/:id	TEACHER, ADMIN	Détail d'un quiz.	—	quizPublicSchema
PATCH	/teacher/quizzes/:id	TEACHER, ADMIN	Met à jour passingScore / isRequired.	updateQuizInputSchema	quizPublicSchema
DELETE	/teacher/quizzes/:id	TEACHER, ADMIN	Soft delete du quiz (204).	—	—
POST	/teacher/quizzes/:quizId/questions	TEACHER, ADMIN	Ajoute une question au quiz.	questionInputSchema	questionPublicSchema
GET	/teacher/quizzes/:quizId/questions	TEACHER, ADMIN	Liste les questions du quiz.	—	questionPublicSchema[]
PATCH	/teacher/quizzes/:quizId/questions/reorder	TEACHER, ADMIN	Réordonne les questions.	reorderInputSchema	questionPublicSchema[]
PATCH	/teacher/questions/:id	TEACHER, ADMIN	Remplace une question.	questionInputSchema	questionPublicSchema
DELETE	/teacher/questions/:id	TEACHER, ADMIN	Supprime une question (hard delete, 204).	—	—

Ressources teacher (/teacher/resources, /teacher/courses/:courseId/resources)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/courses/:courseId/resources	TEACHER, ADMIN	Liste les ressources d'un cours.	—	resourcePublicSchema[]
POST	/teacher/courses/:courseId/resources	TEACHER, ADMIN	Ajoute une ressource (PDF ou LIEN).	createResourceInputSchema	resourcePublicSchema
PATCH	/teacher/resources/:id	TEACHER, ADMIN	Met à jour une ressource.	updateResourceInputSchema	resourcePublicSchema
DELETE	/teacher/resources/:id	TEACHER, ADMIN	Soft delete (204).	—	—

Inscriptions learner (/enrollments)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/enrollments/me	JWT	Liste les inscriptions de l'apprenante (avec résumé du cours).	—	enrollmentWithCourseSchema[]
GET	/enrollments/:id	JWT	Détail d'une inscription (ownership).	—	enrollmentPublicSchema

Quiz learner (/quizzes)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/quizzes/:id	JWT	Vue learner d'un quiz (sans correctIndex).	—	quizLearnerSchema
POST	/quizzes/:id/attempts	JWT	Soumet une tentative ; le score est calculé serveur.	submitQuizAttemptInputSchema	quizAttemptResponseSchema

Progression learner (/sections, /courses)

Méthode	Chemin	Auth	Description	Input schema	Output schema
POST	/sections/:id/complete	JWT	Marque la section comme terminée (idempotent).	—	sectionProgressResponseSchema
GET	/courses/:id/progress	JWT	Vue progression complète pour le player (sections, quiz, déblocages).	—	courseProgressSchema

Certificats (/certificates)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/certificates/me	JWT	Liste des certificats émis pour le user courant.	—	certificateMineSchema[]
GET	/certificates/:shareToken	public	Vue partageable d'un certificat (token opaque cuid).	—	certificateSharedSchema

Paiements (/payments)

Méthode	Chemin	Auth	Description	Input schema	Output schema
POST	/payments	LEARNER, ADMIN	Déclenche un paiement (stub MVP : SUCCEEDED + Enrollment en cascade).	createPaymentInputSchema	paymentCreateResponseSchema
GET	/payments/me	JWT	Historique des paiements du user courant.	—	paymentPublicSchema[]
POST	/payments/webhook	public	Webhook stub réservé (les gateways réelles signeront via HMAC en v1.1).	—	{ ok: true } (ad hoc)

Tableau de bord teacher (/teacher)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/teacher/stats/dashboard	TEACHER, ADMIN	Statistiques globales de la teacher (revenus, learners, complétion).	—	teacherDashboardStatsSchema
GET	/teacher/enrollments	TEACHER, ADMIN	Inscriptions cross-cours (paginé : page, pageSize, courseId, completed, q).	query params	teacherEnrollmentsListSchema

Espace admin — utilisateurs (/admin/users)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/admin/users	ADMIN	Liste paginée des users (filtres : role, includeDeleted).	query params	adminUsersListSchema
GET	/admin/users/:id	ADMIN	Détail d'un user (avec inscriptions ou cours selon le rôle).	—	adminUserDetailSchema
POST	/admin/users	ADMIN	Crée un user TEACHER ou ADMIN (mot de passe temporaire renvoyé).	createAdminUserInputSchema	adminUserWithTempPasswordSchema
PATCH	/admin/users/:id	ADMIN	Met à jour email / name / role d'un user.	updateAdminUserInputSchema	adminUserPublicSchema
DELETE	/admin/users/:id	ADMIN	Soft delete (204).	—	—
POST	/admin/users/:id/reset-password	ADMIN	Réinitialise et renvoie un mot de passe temporaire.	—	adminUserWithTempPasswordSchema

Espace admin — cours (/admin/courses)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/admin/courses	ADMIN	Liste paginée des cours (filtres : status, includeDeleted).	query params	adminCoursesListSchema
GET	/admin/courses/:id	ADMIN	Détail admin d'un cours (modules + audience).	—	adminCourseDetailSchema
PATCH	/admin/courses/:id	ADMIN	Override du statut directement (DRAFT / PUBLISHED / DISABLED / ARCHIVED).	adminUpdateCourseInputSchema	adminCoursePublicSchema

Espace admin — statistiques (/admin/stats)

Méthode	Chemin	Auth	Description	Input schema	Output schema
GET	/admin/stats	ADMIN	Compteurs users / cours / revenus + inscriptions par mois.	—	adminStatsSchema

Note d'évolution

Cette page est maintenue manuellement : à chaque ajout d'endpoint, pensez à compléter le tableau du domaine concerné (et à référencer le schéma Zod correspondant). Une génération automatique via OpenAPI (à partir des décorateurs NestJS et des schémas @app/contracts) est envisagée en v1.1 pour éliminer ce travail manuel et garantir la cohérence avec le code.