
Lundi matin, Samuel ouvre un ticket au titre inquiétant :
Une demande s’est approuvée toute seule.
Vous remontez le fil avec Karim. Vendredi, il a collé le lien d’approbation de la demande d’Amina Diallo dans la messagerie de l’équipe, pour demander l’avis d’un collègue. La messagerie a aussitôt affiché un aperçu du lien : pour le construire, elle a envoyé une requête
GETà l’adresse… et approuvé la demande. Puis Karim, convaincu, a cliqué lui-même sur le lien. Hamac a approuvé la demande une seconde fois, et décompté deux fois les jours d’Amina.
Dans le même temps, Inès vous annonce que le branchement du front-end Blazor commence la semaine prochaine. L’écran actuel, qui fonctionne sur des données simulées, a besoin de quatre opérations : consulter un solde, lister les demandes, déposer une demande, approuver ou refuser. L’API n’en propose que deux, et vous savez dans quel état.
L’incident de vendredi n’est pas un bug de la messagerie. Le protocole HTTP définitGETcomme un verbe sûr : une requêteGETsert à lire, et ne doit jamais modifier de données. Tous les outils du web s’appuient sur cette garantie. Les messageries ouvrent les liens pour en afficher un aperçu, les navigateurs préchargent les pages, les moteurs de recherche suivent tous les liens qu’ils trouvent. Aucun d’eux ne se méfie d’unGET.
En approuvant une demande sur unGET, le starter a rompu cette garantie. Et commeApprovene vérifie pas le statut de la demande, rien n’a empêché la seconde approbation. Deux défauts se sont combinés : un verbe mal choisi et une règle métier absente. Vous allez corriger les deux.
Les routes du starter décrivent des actions :api/leave/balance,api/leave/approve. Une API REST s’organise plutôt autour de ressources : les objets métier que le client manipule, désignés par des noms. Dans Hamac, il y en a deux : les salariés et les demandes de congés. Chaque ressource a une adresse, et le verbe HTTP indique ce que l’on veut en faire.
Besoin du front-end | Route du starter | Route du nouveau contrat |
Consulter le solde d’un salarié |
|
|
Lister les demandes, éventuellement par statut | — |
|
Consulter une demande | — |
|
Déposer une demande | — |
|
Approuver une demande |
|
|
Refuser une demande | — |
|
Remarquez la différence entre l’identifiant et le filtre. L’identifiant désigne une ressource précise : il fait partie du chemin (leave-requests/7). Le filtre restreint une liste : il passe dans la chaîne de requête (?status=Pending). Ce découpage détermine aussi les réponses : une demande n° 999 qui n’existe pas mérite un404, alors qu’une liste filtrée sans résultat est simplement une liste vide.
Le contrat répartit aussi ces routes entre deux contrôleurs, un par ressource :EmployeesControlleretLeaveRequestsController. C’est la responsabilité unique appliquée aux contrôleurs.
Lire un solde, lister ou consulter des demandes ne modifie rien : c’est le rôle deGET. Déposer une demande crée une nouvelle ressource : c’est le rôle dePOSTsur la collectionleave-requests.
L’approbation demande plus de réflexion. Elle modifie une demande existante, mais ce n’est pas une simple modification : elle déclenche une règle métier, met à jour le salarié et envoie une notification. Le contrat la représente donc comme la création d’une décision, avec unPOSTsur une sous-ressource :leave-requests/7/approval.
Pourquoi ne pas utiliserPATCH api/leave-requests/7avec{ "status": "Approved" }?
Parce que ce contrat permettrait au client de choisir n’importe quel statut. Rien n’empêcherait d’envoyerApprovedpour une demande que le solde ne couvre pas, ou de repasser une demande refusée en attente. Le statut d’une demande n’est pas une donnée que l’on modifie librement, c’est le résultat d’une décision encadrée par les règles RH. Une route dédiée à chaque décision garde ces règles du côté du serveur.
Le starter répond200à tout, y compris quand le salarié n’existe pas :Ok("Employee not found"). Pour savoir si la requête a réussi, le front-end devrait donc lire le texte de la réponse et le comparer à des chaînes connues. Le jour où quelqu’un corrigera une faute de frappe dans ce message, le front-end cessera de détecter l’erreur.
Le code de statut est fait pour ça : c’est la partie de la réponse que tous les clients savent interpréter, sans connaître votre API. Le nouveau contrat en utilise cinq :
Statut | Signification | Dans Hamac |
| La requête a réussi, la réponse contient le résultat. | Un solde, une liste, une demande après décision |
| Une ressource a été créée. L’en-tête | Une demande déposée |
| Les données envoyées sont invalides. | Une date de fin antérieure à la date de début |
| La ressource désignée par l’adresse n’existe pas. | La demande n° 999 |
| La requête est valide, mais incompatible avec l’état actuel de la ressource. | Approuver une demande déjà traitée |
Le409correspond exactement à la seconde approbation de Karim. La demande existe et la requête est bien formée, mais la demande n’est plus en attente : la décision a déjà été prise. Pour renvoyer ce statut, le service doit d’abord connaître cette règle. C’est une règle métier que le starter avait oubliée, et Samuel vous a confirmé qu’une demande ne se traite qu’une fois.
Si le solde ne couvre pas la demande, l’approbation aboutit à un refus. Pourquoi ne pas répondre par une erreur ?
Parce que la requête a bien été traitée. La règle RH prévoit qu’une demande non couverte par le solde est refusée, et ce refus est enregistré. Une réponse4xxsignifierait au contraire que le serveur n’a rien fait. L’API répond donc200, avec la demande à jour : son statutRefusedindique le résultat de la décision.
Pour lister les demandes, le plus rapide serait de renvoyer directement les entités :return Ok(_db.LeaveRequests.ToList()). Le réflexe le plus risqué consiste justement à faire de vos entités le contrat de votre API.
Une entité décrit la façon dont les données sont stockées. Le contrat décrit ce que le client peut voir et envoyer. Si les deux se confondent, chaque évolution de la base devient une évolution de l’API. Renommez une colonne, et le front-end cesse de fonctionner. Ajoutez un champ interne àEmployee, comme une note de la RH, et il est exposé à tous les clients sans que personne ne l’ait décidé.
Un DTO (Data Transfer Object) est un objet qui ne sert qu’à transporter des données entre l’API et ses clients. Il contient exactement les champs du contrat, ni plus ni moins. Hamac en a besoin de trois :
public sealed record BalanceDto(int EmployeeId, double Balance);
public sealed record LeaveRequestDto(
int Id,
int EmployeeId,
DateTime StartDate,
DateTime EndDate,
int WorkingDays,
string Status)
{
public static LeaveRequestDto From(LeaveRequest request) => new(
request.Id,
request.EmployeeId,
request.StartDate,
request.EndDate,
request.WorkingDays,
request.Status);
}Le troisiéme,CreateLeaveRequestDto, décrit les données attendues pour déposer une demande. Il ne contient que trois champs : le salarié, la date de début et la date de fin. Le nombre de jours ouvrés est calculé par le service, et le statut initial est toujoursPending: le client ne peut décider ni de l’un ni de l’autre. Vous l’écrirez dans la section suivante, avec ses règles de validation.
Les DTO de sortie sont desrecord: leurs valeurs sont fixées à la création et ne changent plus, ce qui correspond à leur rôle de simple message. La méthodeFromcentralise la conversion d’une entité en DTO. Le service continue de manipuler des entités, et ce sont les contrôleurs qui les convertissent en DTO au moment de répondre : le contrat de l’API reste ainsi une affaire de la couche HTTP.
Vos contrôleurs portent depuis le début l’attribut[ApiController]. Il active plusieurs comportements, dont deux vous concernent directement :
il déduit d’où viennent les paramètres : un type simple commeint idest lu dans la route ou la chaîne de requête, un type complexe commeCreateLeaveRequestDtodans le corps de la requête, au format JSON ;
il valide automatiquement les données reçues. Si elles ne respectent pas les règles déclarées, l’action n’est même pas appelée : le framework répond directement400, avec le détail des erreurs.
Les règles de validation se déclarent sur le DTO, avec des attributs appelés Data Annotations :
public sealed class CreateLeaveRequestDto : IValidatableObject
{
[Range(1, int.MaxValue)]
public int EmployeeId { get; init; }
[Required]
public DateTime? StartDate { get; init; }
[Required]
public DateTime? EndDate { get; init; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
if (EndDate < StartDate)
{
yield return new ValidationResult(
"La date de fin doit être postérieure ou égale à la date de début.",
[nameof(EndDate)]);
}
}
}Un détail piège souvent les développeurs : les dates sont déclaréesDateTime?, et nonDateTime. UnDateTimene peut pas être vide. Si le client oublie le champ, il prend sa valeur par défaut, le 1er janvier de l’an 1, et[Required]le considère comme rempli. Avec un type nullable, un champ absent vautnull, et la validation échoue comme prévu. PourEmployeeId, c’est[Range]qui joue ce rôle : un identifiant absent vaut0, et la règle exige au moins1.
La cohérence entre les deux dates ne peut pas s’exprimer avec un attribut sur un seul champ. L’interfaceIValidatableObjectpermet d’ajouter des règles qui portent sur plusieurs champs : le framework appelleValidateaprès avoir vérifié les attributs.
Voici la réponse obtenue pour une demande dont la date de fin précède la date de début (simplifiée) :
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"EndDate": ["La date de fin doit être postérieure ou égale à la date de début."]
}
}Le front-end pourra afficher ce message sous le bon champ du formulaire, sans rien deviner.
Un salarié inexistant pose une dernière question : quel statut renvoyer ? Pas404, car la ressource désignée par l’adresse, la collectionleave-requests, existe bien. Ce sont les données envoyées qui sont invalides : la réponse est un400, au même format que les erreurs de validation.
Les erreurs de validation suivent un format standard, appelé Problem Details et décrit par la RFC 9457. Pour que toutes les erreurs de l’API, et pas seulement celles-là, adoptent ce format, ajoutez deux lignes àProgram.cs:
builder.Services.AddProblemDetails();
// Après builder.Build() :
app.UseExceptionHandler();AddProblemDetailsactive ce format pour les réponses d’erreur.UseExceptionHandlerajoute un middleware qui intercepte les exceptions non gérées et les transforme en réponse500au même format, sans exposer le détail de l’exception en production. Le front-end n’a plus qu’un seul format d’erreur à traiter, quelle que soit sa cause.
Dans les contrôleurs,NotFound()produit automatiquement une réponse dans ce format, grâce à[ApiController]. Pour un conflit, la méthodeProblempermet d’ajouter un titre explicite :
Problem(statusCode: StatusCodes.Status409Conflict, title: "Cette demande a déjà été traitée.")Un contrat ne sert que s’il est connu de ceux qui l’utilisent. OpenAPI est un format standard qui décrit une API : ses routes, ses paramètres, ses DTO et ses réponses possibles. ASP.NET Core sait le générer à partir de vos contrôleurs. Ajoutez le paquet correspondant :
dotnet add src/Hamac.Api package Microsoft.AspNetCore.OpenApiPuis activez-le dansProgram.cs, uniquement en développement :
builder.Services.AddOpenApi();
// Après builder.Build() :
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}La description est alors disponible à l’adressehttp://localhost:5110/openapi/v1.json. C’est ce document que vous transmettrez à l’équipe qui branche le front-end. Les types de retour de vos actions, commeActionResult<LeaveRequestDto>, y apparaissent automatiquement : c’est une raison supplémentaire de les déclarer précisément.
Pour essayer le contrat sans écrire de commandescurlà rallonge, utilisez un fichier.http. Visual Studio et Rider l’exécutent nativement ; dans VS Code, installez l’extension REST Client. Créezsrc/Hamac.Api/Hamac.Api.http:
@baseUrl = http://localhost:5110
### Solde de Leïla Haddad
GET {{baseUrl}}/api/employees/4/balance
### Demandes en attente
GET {{baseUrl}}/api/leave-requests?status=Pending
### Approuver la demande n° 7
POST {{baseUrl}}/api/leave-requests/7/approval
### Déposer une demande invalide
POST {{baseUrl}}/api/leave-requests
Content-Type: application/json
{ "employeeId": 4, "startDate": "2026-07-10", "endDate": "2026-07-06" }Ce fichier a un second usage : versionné avec le code, il montre à la prochaine personne qui rejoindra l’équipe comment appeler chaque route.
Au chapitre 3, vous ne deviez pas modifier les tests : un refactoring ne change pas le comportement observable. Ici, la situation est différente. Vous changez volontairement le contrat de l’API, et les tests qui appellent les anciennes routes vont échouer. C’est normal, et c’est même utile : chaque test en échec signale un endroit où un client de l’API serait cassé.
Mettez donc à jour les tests existants pour qu’ils utilisent les nouvelles routes, puis ajoutez des tests pour les nouveaux comportements du contrat : les statuts d’erreur, la validation et l’interdiction de traiter deux fois une demande.

Inès veut que le contrat soit prêt lundi, quand commencera le branchement du front-end. Samuel, lui, attend une seule chose : que l’incident de vendredi ne puisse plus se reproduire.
Ajoutez une classeLeaveStatusescontenant les trois statuts sous forme de constantes, et utilisez-la dans le service.
DansLeaveService, interdisez d’approuver une demande qui n’est plus en attente, puis ajoutez les méthodesGetRequests,GetRequest,CreateetRefuse. PourCreate, comptez les jours ouvrés du lundi au vendredi, sans tenir compte des jours fériés.
Créez les trois DTO, avec les règles de validation deCreateLeaveRequestDto.
RemplacezLeaveControllerparEmployeesControlleretLeaveRequestsController, qui exposent les six routes du nouveau contrat avec les statuts adaptés.
Activez Problem Details et OpenAPI dansProgram.cs.
Créez le fichierHamac.Api.httpet rejouez le scénario de l’incident : deux approbations successives de la même demande.
Mettez à jour les tests existants, puis ajoutez au moins un test pour la double approbation et un test pour la validation des dates.
Point de contrôle : les six routes répondent avec les statuts du contrat. Une seconde approbation de la même demande renvoie409. Aucune action ne renvoie d’entité. Tous les tests passent. Enregistrez votre travail avec Git.
Une API REST s’organise autour de ressources désignées par des noms. Le verbe HTTP indique ce que l’on veut en faire, et unGETne modifie jamais de données.
Une décision encadrée par des règles métier se représente par une route dédiée, plutôt que par une modification libre du statut.
Les codes de statut indiquent le résultat de la requête à tous les clients :200,201,400,404ou409selon le cas.
Les DTO séparent le contrat de l’API du schéma de la base, et empêchent le client de remplir des champs qu’il ne doit pas contrôler. Ils valident ce qui se juge en lisant la requête ; le service vérifie ce qui demande de consulter les données.
Problem Details donne un format unique à toutes les erreurs. OpenAPI, un fichier.httpet des tests d’API documentent et protègent le contrat.
Hamac dispose maintenant d’un contrat d’API clair, documenté et testé, et l’incident de vendredi ne peut plus se reproduire. Dans le dernier chapitre, vous allez brancher le front-end Blazor sur ce contrat, ajouter enfin la politique des stages et documenter l’application pour la prochaine personne qui la reprendra.