1. Ce cours a besoin de son propre projet
Le projet fil rouge dans ce cours remplit plusieurs fonctions importantes à la fois. Premièrement, il réduit le bruit cognitif. Au lieu de te demander à chaque fois quelles entités existent ici, comment elles sont liées et pourquoi elles existent, tu entres une seule fois dans le domaine, et ensuite tu travailles directement avec les idées d'API.
Deuxièmement, le projet fil rouge donne une sensation d'accumulation de résultats. Si un cours se compose de mini-démos sans lien, difficile de ressentir la progression : tu vois plein de fragments différents, mais pas un seul objet qui soit réellement devenu plus solide. Ici c'est l'inverse : une même API parcourt progressivement le chemin de l'idée et de la carte des ressources jusqu'aux DTO, à la validation, au contrat d'erreurs, aux patterns pour les listes, aux endpoints de fichiers, à la documentation et aux tests web.
Troisièmement, un seul projet rend le cours plus honnête en tant que récit d'ingénierie. Dans le vrai travail, un développeur backend n'écrit presque jamais « aujourd'hui un endpoint, demain on l'oublie et on commence un autre projet ». Le vrai travail, c'est faire évoluer une API déjà existante. Ajouter de nouveaux scénarios. Maintenir la rétrocompatibilité. Aligner les nouvelles décisions avec le contrat existant.
C'est pourquoi Task Tracker API n'est pas ici un « exemple pour l'exemple », mais le fil conducteur du cours. Tous les grands thèmes y reviennent constamment. Et c'est très utile : tu verras le même objet d'abord comme domaine, puis comme ensemble de ressources, puis comme contrat JSON, puis comme objet de validation, puis comme source d'erreurs métier, et enfin comme sujet de tests.
2. Task Tracker — un bon compromis ⚖️
Le domaine des tâches est presque idéal pour un cours sur la conception d'API REST. Il est suffisamment familier pour ne pas perdre de temps à expliquer « ce qui se passe exactement », et suffisamment riche pour montrer de nombreux scénarios réels. Presque tout développeur a déjà vu des tâches dans Jira, Trello, Notion, Asana ou même dans sa liste to-do personnelle.
En même temps, une tâche n'est pas « juste une ligne de texte » 📝. Elle fait naturellement apparaître différents types de données et différents comportements. Il y a un titre et une description. Il y a un statut et une priorité. Il y a une date limite. Il y a des tags. Il y a des commentaires. Il y a des pièces jointes. Il y a un moment de création et de mise à jour. Déjà sur un seul objet on peut montrer beaucoup de choses critiques dans une vraie API : quels champs sont publics, lesquels sont obligatoires, lesquels sont gérés par le serveur, à quoi ressemblent le list-view et le detail-view, comment concevoir la update semantics.
Si on avait choisi un domaine trop simple, le cours aurait vite atteint ses limites. Il n'y aurait pas eu matière pour montrer les list patterns, le file upload, les business transitions, les subresources et un modèle d'erreurs correct. Si on avait choisi un domaine trop lourd, le cours se serait noyé dans la complexité métier. C'est pourquoi Task Tracker est excellent précisément comme compromis : il est suffisamment vivant, mais n'exige pas de transformer le projet en mini-Jira.
Un autre avantage : ce domaine se transpose bien au développement commercial. Même si tu travailles ensuite non pas sur un task tracker, mais sur une API de demandes, de tickets, de commandes, de cas de support ou d'entités workflow internes, la majorité des décisions de contrat sera très similaire.
3. L'objet central du projet : Task et sa forme de travail
Le cœur du projet, c'est la tâche. Et c'est précisément parce qu'elle est centrale qu'elle doit être suffisamment riche pour porter les futures questions API 🔍. Il est utile ici de regarder non seulement les noms des champs, mais aussi pourquoi ils existent du point de vue du cours.
Voici à peu près comment on peut penser la forme de travail interne d'une tâche :
// Statut — clé pour discuter des transitions d'état et des conflits (409, etc.)
enum TaskStatus {
TODO, // tâche créée, pas encore prise en charge
IN_PROGRESS, // en cours d'exécution
BLOCKED, // bloquée, impossible d'avancer
DONE, // terminée
ARCHIVED // "mise de côté" : existe, mais généralement non modifiable
}
// Priorité — axe pratique pour le tri/filtrage et les règles métier
enum TaskPriority {
LOW, // peut attendre
MEDIUM, // niveau habituel
HIGH, // important
CRITICAL // urgent, impact sur le système/l'équipe
}
class Task {
String id; // identifiant de ressource côté serveur (adressage /tasks/{id})
String title; // titre court : presque toujours obligatoire → validation
String description; // détails : souvent optionnel, mais important pour l'UX
TaskStatus status; // état : détermine les opérations autorisées
TaskPriority priority; // priorité : influence le tri et les scénarios de type SLA
LocalDate dueDate; // date limite : utile pour les filtres "en retard/cette semaine"
String assigneeName; // assigné : simplifié (sans entité User séparée)
List<String> tags; // tags : modèle léger de type "value" pour la recherche/filtrage
Instant createdAt; // champ géré par le serveur : défini à la création
Instant updatedAt; // champ géré par le serveur : mis à jour lors des modifications
}Même ce court fragment est déjà très utile pour le cours. id soulève immédiatement la question de la ressource et de l'adressage. title et description mènent à la validation de l'entrée et aux modèles JSON. status permet de discuter des transitions d'état et des scénarios de conflit. priority, dueDate, assigneeName et tags fournissent du matériel pour le filtrage, le tri et la recherche. createdAt et updatedAt rappellent que le serveur gère lui-même une partie des données.
Pour mieux le ressentir, il est utile de regarder les champs non pas comme une « liste d'attributs », mais comme les futurs thèmes du cours :
| Champ de la tâche | Ce qu'il apporte au cours |
|---|---|
| id | l'adressage des ressources et le fonctionnement des detail-endpoints |
title / |
le DTO de requête, la validation et la forme de la réponse |
| status | la sémantique des mises à jour, les transitions d'état et 409 Conflict |
priority / |
le tri, le filtrage et le comportement de la liste |
| tags | la recherche, le filtrage et les scénarios de lookup légers |
createdAt / |
les champs gérés par le serveur et la discipline du modèle public |
Voilà ce qu'il est important de voir ici. On choisit intentionnellement non pas une abstraite « Entity with id and name », mais un objet qui soulève naturellement des questions d'API. Cela rend le projet porteur vivant du cours, et non simplement un décor pour les annotations.
4. Commentaires, tags, pièces jointes et statuts 🔗
Si le projet ne contenait que l'entité Task, le cours serait moins riche. C'est pourquoi à côté de Task existent des objets liés qui n'alourdissent pas le domaine, mais augmentent fortement la valeur pédagogique 💪.
Les commentaires sont nécessaires pour qu'il y ait une vraie sous-ressource dans le projet. C'est un scénario très courant dans la vie réelle. La tâche existe par elle-même, et les commentaires lui appartiennent et vivent à côté. Cela aide ensuite à parler très naturellement des subresources, du comportement list/detail et de comment éviter de tout transformer en un ensemble RPC non structuré.
Voici à peu près comment on peut penser un commentaire :
class Comment {
String id; // identifiant du commentaire (généralement unique dans toute l'API)
String taskId; // référence à la tâche parente : sous-ressource /tasks/{taskId}/comments
String authorName; // qui a écrit (pour le cours — simple chaîne sans entité User)
String text; // texte du commentaire : excellent candidat à la validation (non vide, limites de longueur)
Instant createdAt; // géré par le serveur : l'heure de création est fixée côté serveur
}Les tags ne sont pas là parce que « c'est à la mode dans les trackers », mais parce qu'ils se prêtent parfaitement aux scénarios de filtrage et de lookup. Dans ce cours, les tags ne doivent pas se transformer en une grosse entité séparée avec son propre CRUD complet. Ici, ils sont légers, de type valeur, et utiles.
Les pièces jointes sont nécessaires parce que les scénarios de travail avec des fichiers font partie du quotidien d'un serveur, et non d'une exotique rarété 📎. Grâce à elles, le cours obtient un prétexte très naturel pour parler du multipart upload, du téléchargement, du split metadata/content et de la configuration du stockage local, sans partir dans les clouds et une infrastructure lourde.
Les statuts apportent une couche de comportement très utile 🚦. Tant qu'une tâche ne fait que stocker du texte, l'API se réduit facilement à du CRUD basique. Mais dès que la tâche a un état, un sujet plus mature apparaît : toutes les modifications ne se valent pas. L'archivage, le blocage, la finalisation, le retour en cours de travail — tout cela aide ensuite à parler non seulement des champs, mais aussi du sens métier des opérations.
5. Ce domaine couvre presque tout le cours
Un bon projet fil rouge ne « contient » pas simplement « beaucoup d'entités ». Il est structuré de façon à ce que les différentes parties du domaine soutiennent naturellement les différents thèmes du cours. Task Tracker API est exactement ainsi.
| Partie du projet | Quel thème du cours elle aide à développer |
|---|---|
|
CRUD de base et pensée REST |
|
list-endpoints, pagination, tri et filtrage |
| status | sémantique des mises à jour, conflits métier et gestion des erreurs |
|
subresources et collections dépendantes |
|
upload via multipart, téléchargement de fichiers et séparation metadata/content |
|
filtrage, recherche et scénarios de lookup légers |
title, |
validation et contrat d'entrée |
| tous les modèles de réponse ensemble | DTO, Jackson et la discipline de la forme de réponse |
| negative-path sur données absentes et conflits | ProblemDetail et contrat d'erreurs unifié |
| couche web prête | OpenAPI et @WebMvcTest |
Ce tableau est très important. Il montre que le cours ne se compose pas de 150 leçons aléatoires. Il assemble vraiment une API, couche par couche. Et Task Tracker API est là non pas juste comme « une histoire intéressante », mais comme une structure portante bien choisie.
Remarque aussi autre chose. On n'a pas ajouté au projet des entités artificielles juste pour « couvrir le programme ». Au contraire, presque tout semble naturel. Les tâches ont des commentaires. On joint des fichiers aux tâches. On filtre les tâches par statut, priorité, date limite et tags. Les tâches passent d'un état à un autre. C'est la vie applicative tout à fait normale d'une API backend ordinaire.
6. Comment le projet se présente aux yeux du client
Jusqu'ici on a parlé du domaine. Mais il est déjà utile de le tourner légèrement vers l'extérieur — non pas pour aborder le thème complet du design des URI, mais pour voir comment le client le perçoit. De l'extérieur, Task Tracker API se présentera non pas comme un ensemble de classes Task, Comment et AttachmentMetadata, mais comme un ensemble de ressources et de scénarios associés.
Au niveau le plus grossier, le client s'attend à ce que la carte des ressources de l'API ressemble à peu près à ceci :
# Collection de base de tâches (list/create)
/api/v1/tasks
# Tâche spécifique (detail/update/delete)
/api/v1/tasks/{taskId}
# Sous-ressource : commentaires d'une tâche spécifique (list/create)
/api/v1/tasks/{taskId}/comments
# Sous-ressource : pièces jointes d'une tâche spécifique (upload/list/download)
/api/v1/tasks/{taskId}/attachments
# Lookup léger sur les tags (si on en fait un endpoint séparé)
/api/v1/tagsCe n'est pas encore la carte finale des endpoints ni une discussion sur toutes les règles du design URI. Mais déjà ces quelques lignes montrent quelque chose d'important : de l'extérieur, le projet s'organise autour de la ressource task, et les autres parties vivent autour d'elle comme des objets de soutien.
Pour mieux ressentir ça, il suffit de regarder comment une tâche peut apparaître en JSON :
{
// Identifiant : généralement attribué par le serveur et utilisé dans l'URL
"id": "t-42",
// Titre lisible par l'humain : champ clé pour la validation
"title": "Fix validation error format",
// Description : aide à montrer la différence entre detail-view et list-view
"description": "Return a consistent error payload for invalid task input",
// Statut : base pour discuter des transitions et des conflits
"status": "IN_PROGRESS",
// Priorité : champ typique pour le tri
"priority": "HIGH",
// Date limite : bon exemple de date (sans heure) et de filtres par période
"dueDate": "2026-04-01",
// Assigné : dans le cours — chaîne, pour ne pas traîner un domaine user séparé
"assigneeName": "Alex",
// Tags : modèle léger pour la recherche/filtrage (et pour montrer les tableaux)
"tags": ["api", "validation"]
}Et un commentaire peut ressembler à ceci :
{
// Identifiant du commentaire
"id": "c-10",
// Référence à la tâche parente (important pour les sous-ressources et la cohérence)
"taskId": "t-42",
// Auteur (simplifié en chaîne)
"authorName": "Maria",
// Texte du commentaire (excellent endroit pour des règles : non vide, limite de longueur)
"text": "I reproduced it with empty title",
// Heure de création : géré par le serveur, pratique pour le tri chronologique
"createdAt": "2026-03-21T11:10:00Z"
}Et c'est déjà suffisant pour voir le fil rouge du cours. On ne va pas changer le monde chaque jour. On va prendre une seule et même API et la rendre de plus en plus mature aux yeux du client.
7. Erreurs typiques dans l'évaluation d'un projet pédagogique 🚧
Erreur n°1 : percevoir le projet pédagogique comme « trop simple, donc pas sérieux ».
La sérieux d'un projet pédagogique ne se mesure pas au nombre d'entités, mais à l'honnêteté avec laquelle il porte les questions d'ingénierie nécessaires. Task Tracker API offre suffisamment de matière pour un vrai design d'API REST sans lourdeur de domaine inutile.
Erreur n°2 : essayer de transformer le projet en mini-Jira.
La tentation d'ajouter des utilisateurs, des équipes, des tableaux, des épopées, l'historique des modifications, des notifications et encore vingt entités vient très vite. Cela détruit presque toujours le focus pédagogique. Le projet doit être non pas « plus grand », mais mieux choisi.
Erreur n°3 : ne pas voir le lien entre le domaine et les thèmes du cours.
Si on regarde Task, Comment ou Attachment simplement comme des noms de classes, le projet semble ordinaire. Mais dès qu'on remarque quels patterns d'API ils portent, on voit pourquoi le domaine a été choisi ainsi.
Erreur n°4 : penser que le projet fil rouge n'est qu'un décor.
En réalité, c'est l'un des principaux piliers pédagogiques du cours. Il est là pour que chaque nouvelle couche de qualité ne flotte pas dans le vide, mais s'appuie sur un système déjà familier.
GO TO FULL VERSION