Connectez le front-end fourni et documentez votre application

Au chapitre précédent, vous avez livré à Inès un contrat d’API clair, documenté et testé. Mais pour Samuel, rien n’a changé : l’écran qu’il utilise affiche toujours des données simulées. Il voit des demandes qui n’existent pas, et un solde qui n’est pas le sien.

Inès vous transmet la suite. L’équipe front-end a terminé la réécriture de l’écran Blazor, mais elle est partie sur un autre projet sans le brancher. 

Tout est prêt côté interface, il ne manque que les appels à l’API.

Samuel veut faire tester l’écran par Karim vendredi. Il a une autre échéance en tête : Zoé Mendes, la première stagiaire de l’entreprise, arrive lundi prochain, et son solde doit s’afficher dès son premier jour.

Inès ajoute une dernière demande. Tomás Herrera rejoindra l’équipe le mois prochain, et c’est lui qui maintiendra Hamac.

Je veux qu’il puisse lancer l’application sans m’appeler. Toi, tu n’as pas eu cette chance. 

Repérez ce que le front-end attend de l’API

Le projetsrc/Hamac.Frontest une application Blazor WebAssembly : elle est téléchargée puis exécutée dans le navigateur de l’utilisateur, et elle écoute en développement surhttp://localhost:5200. Ouvrez son dossierServices. Vous y trouvez trois fichiers :

  • ILeaveApi.cs, une interface qui liste tout ce que les écrans demandent aux données ;

  • MockLeaveApi.cs, qui implémente cette interface avec des listes écrites en dur ;

  • LeaveApiException.cs, l’exception que les écrans interceptent pour afficher un message d’erreur.

public interface ILeaveApi
{
    Task<double> GetBalanceAsync(int employeeId);
    Task<IReadOnlyList<LeaveRequestViewModel>> GetRequestsAsync(string? status);
    Task<LeaveRequestViewModel> CreateRequestAsync(NewLeaveRequestViewModel request);
    Task<LeaveRequestViewModel> ApproveAsync(int requestId);
    Task<LeaveRequestViewModel> RefuseAsync(int requestId);
}

Dans leProgram.csdu front-end, une seule ligne choisit l’implémentation :

builder.Services.AddScoped<ILeaveApi, MockLeaveApi>();

Vous reconnaissez le principe d’inversion des dépendances, appliqué au chapitre 3 : les écrans dépendent d’un contrat, et leProgram.csdécide de l’implémentation. L’équipe front-end a pu construire et tester tous ses écrans sans attendre l’API. Votre travail consiste à écrire une seconde implémentation,HttpLeaveApi, qui appelle vraiment l’API, puis à changer cette ligne. Vous ne modifierez aucun écran.

Les écrans ne manipulent pas vos DTO : ils utilisent leurs propres classes, appelées ViewModels, rangées dans le dossierModelsdu front-end. C’est normal, car les deux projets sont indépendants. Mais quand le front-end reçoit du JSON, il doit pouvoir le lire avec ses ViewModels. Avant d’écrire le moindre appel, comparez les deux côtés du contrat :

Critère

La question à vous poser

Ce que vous observez dans Hamac

Noms des propriétés

Chaque propriété du ViewModel correspond-elle à un champ du JSON ?

LeaveRequestViewModelattend une propriétéDays, alors que l’API renvoieworkingDays.

Types

Les types sont-ils compatibles ?

Oui :int,double,DateTimeetstringdes deux côtés.

Valeurs

Les valeurs attendues sont-elles celles que l’API produit ?

Oui : le front-end traduit les codesPending,ApprovedetRefused.

Données envoyées

Le JSON envoyé correspond-il au DTO d’entrée ?

Oui :NewLeaveRequestViewModelcontientEmployeeId,StartDateetEndDate.

Erreurs

Le front-end sait-il lire les réponses d’erreur ?

Non :MockLeaveApilève ses exceptions lui-même, il n’a jamais lu de Problem Details.

Les différences de casse ne posent pas de problème : les méthodesGetFromJsonAsyncetReadFromJsonAsynclisent le JSON sans tenir compte des majuscules, etemployeeIdremplit bienEmployeeId. En revanche,DaysetworkingDayssont deux noms différents.

Ce décalage est dangereux, parce qu’il ne provoque aucune erreur. Le sérialiseur JSON de .NET ignore les champs qu’il ne reconnaît pas et laisse les propriétés manquantes à leur valeur par défaut. La colonne « Jours » de l’écran afficherait0pour toutes les demandes, sans exception ni message dans les journaux.

Le réflexe le plus risqué consiste à renommer le champ dans l’API pour faire plaisir à l’écran. Le contrat est publié : il est décrit dans le document OpenAPI, utilisé par le fichier.httpet vérifié par les tests. Le modifier pour un seul client casserait tous les autres. C’est au client de s’aligner sur le contrat, ici avec un attribut qui indique le nom du champ JSON sans changer le nom de la propriété utilisée par les écrans :

[JsonPropertyName("workingDays")]
public int Days { get; set; }

Pourquoi le front-end ne réutilise-t-il pas directement les DTO de l’API ? 

Ce serait possible, en plaçant les DTO dans un projet partagé par les deux applications. Mais le front-end dépendrait alors du code de l’API, et chaque changement de DTO l’obligerait à être recompilé et redéployé. Des classes séparées laissent chaque projet évoluer à son rythme. En contrepartie, il faut vérifier que les deux côtés restent alignés : c’est le rôle de la comparaison que vous venez de faire, et de la documentation OpenAPI.

Remplacez les données simulées par des appels HTTP

Pour appeler l’API, le front-end utilise unHttpClient, la classe .NET qui envoie des requêtes HTTP. Il a besoin d’une adresse de base. Plutôt que de l’écrire dans le code, placez-la dans la configuration. Dans une application Blazor WebAssembly, ce fichier se trouve danswwwroot/appsettings.json, car il est téléchargé par le navigateur avec l’application :

{
  "Api": {
    "BaseUrl": "http://localhost:5110/"
  }
}

Puis, dans leProgram.csdu front-end, enregistrez le client et remplacez l’implémentation simulée :

var apiBaseUrl = builder.Configuration["Api:BaseUrl"]
    ?? throw new InvalidOperationException("Api:BaseUrl is missing in wwwroot/appsettings.json.");

builder.Services.AddScoped(_ => new HttpClient { BaseAddress = new Uri(apiBaseUrl) });
builder.Services.AddScoped<ILeaveApi, HttpLeaveApi>();

Si l’adresse manque, l’application s’arrête au démarrage avec un message explicite, plutôt que d’échouer plus tard sur un appel incompréhensible.

Chaque méthode de l’interface correspond à une route du contrat. La lecture du solde montre le principe : 

public async Task<double> GetBalanceAsync(int employeeId)
{
    var response = await _http.GetAsync($"api/employees/{employeeId}/balance");
    var balance = await ReadAsync<BalanceResponse>(response);
    return balance.Balance;
}

L’API renvoie un objet{ "employeeId": 4, "balance": 4.56 }, alors que l’interface attend un simple nombre. Un petit record privé,BalanceResponse, sert à lire cette réponse. Il n’a pas besoin d’être visible ailleurs : c’est un détail de la traduction entre le contrat HTTP et le contrat des écrans.

Vous écrirez les quatre autres méthodes sur le même modèle, avecGetAsync,PostAsJsonAsyncpour la création etPostAsyncpour l’approbation et le refus.

Toutes les méthodes passent par une méthode privéeReadAsync. Si la réponse est un succès, elle lit le JSON. Sinon, elle lit la réponse Problem Details et lève uneLeaveApiException, que les écrans savent déjà afficher.

private static async Task<T> ReadAsync<T>(HttpResponseMessage response)
{
    if (response.IsSuccessStatusCode)
    {
        return (await response.Content.ReadFromJsonAsync<T>())!;
    }

    throw new LeaveApiException(await ReadErrorMessageAsync(response));
}

C’est ici que le travail du chapitre précédent porte ses fruits. Toutes les erreurs de l’API ont le même format : un champtitle, et un champerrorspour les erreurs de validation. Le front-end n’a donc qu’une seule façon de les lire, quelle que soit leur cause. Une double approbation affichera « Cette demande a déjà été traitée. », et une demande dont la date de fin précède la date de début affichera le message de validation deCreateLeaveRequestDto.

Pourquoi ne pas appeler simplementresponse.EnsureSuccessStatusCode()? 

Cette méthode lève uneHttpRequestExceptionpour toute réponse en erreur, avec un message générique du type « Response status code does not indicate success: 409 (Conflict) ». Elle convient pour un script, mais pas pour un écran : Samuel ne saurait pas s’il doit corriger ses dates ou si quelqu’un a déjà traité la demande. Lire Problem Details permet de lui afficher la vraie raison.

Autorisez le front-end à appeler l’API

Lancez l’API et le front-end dans deux terminaux, puis ouvrezhttp://localhost:5200. L’écran reste vide. Dans les outils de développement du navigateur, onglet Console, un message indique que l’accès àhttp://localhost:5110/api/leave-requestsdepuis l’originehttp://localhost:5200a été bloqué par la politique CORS.

L’API fonctionne pourtant : votre fichier.httpl’appelle sans problème. La différence vient du navigateur. Pour protéger ses utilisateurs, il applique la politique de même origine : un script chargé depuis une origine ne peut lire les réponses d’une autre origine que si celle-ci l’autorise explicitement. Une origine combine le protocole, le nom d’hôte et le port.http://localhost:5200ethttp://localhost:5110sont donc deux origines différentes, même si elles tournent sur la même machine.

Le mécanisme qui permet à l’API d’autoriser une autre origine s’appelle CORS (Cross-Origin Resource Sharing). L’API ajoute à ses réponses des en-têtes qui indiquent quelles origines, quels verbes et quels en-têtes elle accepte. Pour une requêtePOSTavec un corps JSON, le navigateur envoie même une requête préalable, avec le verbeOPTIONS, pour vérifier l’autorisation avant d’envoyer la vraie requête.

Dans ASP.NET Core, CORS est un middleware. Déclarez d’abord une politique dansProgram.csde l’API :

var frontOrigins = builder.Configuration.GetSection("Front:Origins").Get<string[]>() ?? [];

builder.Services.AddCors(options =>
    options.AddPolicy("Front", policy => policy
        .WithOrigins(frontOrigins)
        .WithMethods("GET", "POST")
        .WithHeaders("Content-Type")));

Puis activez-la dans le pipeline, avantMapControllers:

app.UseExceptionHandler();
app.UseCors("Front");

Enfin, déclarez l’origine du front-end dansappsettings.Development.json:

"Front": {
  "Origins": [ "http://localhost:5200" ]
}

Hors développement, la liste est vide et aucune autre origine n’est autorisée. Le jour où le front-end sera déployé, il suffira d’ajouter sa vraie adresse dans la configuration de cet environnement, sans toucher au code.

Le réflexe le plus risqué consiste à copier la configuration la plus courante sur les forums,AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader(), parce qu’elle fait disparaître l’erreur immédiatement. Elle autorise n’importe quel site web à appeler votre API depuis le navigateur de vos utilisateurs. Hamac n’utilise queGETetPOST, et un seul en-tête particulier : autorisez ceux-là, et seulement pour l’origine du front-end.

CORS protège-t-il mon API contre les appels non autorisés ? 

Non. CORS est appliqué par le navigateur, pour protéger l’utilisateur. Un outil commecurl, votre fichier.httpou un autre serveur l’ignorent complètement. Pour empêcher quelqu’un d’appeler votre API, il faut une authentification, qui sort du cadre de ce cours. CORS décide seulement quels sites web ont le droit d’utiliser votre API depuis un navigateur.

Vérifiez le parcours en français et en anglais

Une fois les données réelles affichées, rejouez le parcours métier complet, puis basculez l’écran en anglais avec le sélecteur de langue et recommencez.

Étape

Ce que vous vérifiez

Ce que vous observez dans Hamac

Solde

Le solde est-il celui de l’API, au bon format ?

Leïla Haddad : « 4,56 » en français, « 4.56 » en anglais.

Tableau et filtre

Le filtre par statut appelle-t-il la bonne route ?

Le filtre « En attente » envoie?status=Pendingdans les deux langues.

Statuts

Les statuts sont-ils traduits ?

« En attente » ou « Pending », à partir du même code renvoyé par l’API.

Formulaire

Une demande valide apparaît-elle dans le tableau ? Une demande invalide affiche-t-elle un message ?

La demande créée apparaît avec ses jours ouvrés. L’erreur de dates s’affiche.

Approbation

Une seconde approbation est-elle refusée avec un message clair ?

Le message de conflit s’affiche, et le solde ne change pas.

Cette vérification illustre une décision prise sans le savoir dès le chapitre 3 : l’API renvoie des données, la vue se charge de leur présentation. Le statut circule sous forme de code, et le nombre sous forme de nombre JSON, toujours écrit avec un point. C’est le front-end qui les traduit et les formate selon la langue choisie. Si l’API avait renvoyé « En attente » ou « 4,56 » sous forme de texte, la bascule en anglais aurait été impossible sans modifier l’API.

Vous remarquerez une limite : les messages d’erreur, eux, restent en français dans les deux langues, car ils sont rédigés par l’API. Pour les traduire, le front-end devrait associer son propre message à chaque code de statut. Ce n’est pas indispensable pour vendredi, mais c’est exactement le type d’information à transmettre à Tomás : vous la noterez dans le README.

Ajoutez la politique des stages

Samuel vous transmet le dossier de Zoé Mendes : un contrat de stage, qui commence lundi prochain. Ajoutez-la au jeu de données de démonstration, à la suite des cinq salariés existants, dansDemoData.Reset: 

db.Employees.Add(new Employee
{
    FirstName = "Zoé",
    LastName = "Mendes",
    ContractType = ContractTypes.Internship,
    HireDate = DateTime.Today.AddDays(7),
    DaysTaken = 0
});

Relancez l’API et demandez le solde de Zoé, la salariée n° 6. L’API répond500, et le journal indique la cause :Unknown contract type: Stage. Avec le starter, Hamac lui aurait attribué 0 jour en silence, grâce à sa brancheelse. Vous ne l’auriez découvert qu’à sa première demande de congés. Le résolveur du chapitre 3 rend le problème visible avant que Zoé n’arrive.

Au chapitre 4, vous aviez prévu qu’une classe et une ligne suffiraient pour les stages, auxquelles s’ajoute une constante. Ajoutez d’abord la constanteInternship = "Stage"àContractTypes, puis la politique, sur le modèle de celle des CDD : 2 jours par mois complet de présence.

Avant d’écrire le calcul, regardez la date d’entrée de Zoé : elle est dans le futur. La formule des CDD donneraitMath.Floor(-7 / 30.0), soit-1mois complet, et donc un droit de -2 jours. C’est précisément la situation décrite au chapitre 3 avec le principe de substitution de Liskov : toutes les politiques doivent renvoyer un nombre de jours positif ou nul. Votre politique doit donc renvoyer0tant que le stage n’a pas commencé.

Enfin, ajoutez une seule ligne dansProgram.cs:

builder.Services.AddSingleton<ILeaveEntitlementPolicy, InternshipPolicy>();

Le résolveur reçoit désormais quatre politiques, etLeaveServicen’a pas changé d’une ligne. C’est le principe ouvert/fermé en action : Hamac est ouverte à un nouveau type de contrat, et fermée à la modification du code qui fonctionnait déjà.

La politique des stages ressemble beaucoup à celle des CDD. N’est-ce pas une duplication à supprimer ? 

Le calcul des mois complets est bien le même. Mais les deux règles ne disent pas la même chose : celle des CDD vient du droit du travail, celle des stages est une règle interne fixée par Samuel. Elles pourront évoluer séparément, et c’est pour cela qu’elles vivent dans deux classes. Si la définition du « mois complet » devenait plus précise, par exemple en comptant les mois du calendrier plutôt que des périodes de 30 jours, il serait alors utile d’extraire ce calcul dans une méthode commune. Vous remarquerez au passage que la politique des CDD donne elle aussi un résultat négatif pour une date d’entrée future : ne la corrigez pas en silence, signalez-le à Samuel et à Inès.

Documentez l’application pour la prochaine personne

Quand vous êtes arrivé sur Hamac, vous avez passé un chapitre entier à comprendre comment elle fonctionnait. Le README est le fichier que Tomás ouvrira en premier, à la racine du dépôt, pour s’éviter ce travail. Il ne remplace ni le code ni les tests : il répond aux questions que l’on se pose avant de les lire.

Rubrique

La question à laquelle elle répond

Ce que vous écrivez pour Hamac

Présentation

À quoi sert cette application, et pour qui ?

La gestion des congés, utilisée par les salariés, les managers et l’équipe RH.

Démarrage

Que dois-je installer, et quelles commandes dois-je lancer ?

Le SDK .NET 10, puis une commande par projet, dans deux terminaux.

Configuration

Quels réglages puis-je modifier, et où ?

ConnectionStrings:Hamac,Front:OriginsetApi:BaseUrl.

Architecture

Où se trouve quoi ? Où dois-je intervenir pour une évolution courante ?

Les trois projets, les couches de l’API, et la marche à suivre pour un nouveau type de contrat.

Endpoints

Comment appeler l’API ?

Les six routes, avec un renvoi vers OpenAPI et le fichier.http.

Tests

Comment vérifier que je n’ai rien cassé ?

dotnet test, et ce que couvrent les tests.

Règles métier et limites connues

Qui décide des règles ? Que reste-t-il à faire ?

Samuel valide toute règle RH. Jours fériés ignorés, messages d’erreur non traduits, date d’entrée future pour les CDD.

Le réflexe le plus risqué consiste à rédiger un README exhaustif, qui recopie le code classe par classe. Il sera faux dès la prochaine modification, et personne ne le lira. Visez un document court, qui renvoie vers les sources qui restent à jour d’elles-mêmes : le document OpenAPI pour le contrat, le fichier.httppour les exemples, les tests pour les règles.

Un README se vérifie comme du code. Clonez le dépôt dans un nouveau dossier, suivez les instructions à la lettre, sans rien faire de plus que ce qui est écrit. Chaque fois que vous devez deviner une étape, c’est une ligne qui manque.

À vous de jouer

Inès résume les échéances : « Karim teste l’écran vendredi, Zoé arrive lundi, et Tomás le mois prochain. Je relis ta branche jeudi soir. » 

  1. Corrigez la correspondance entreLeaveRequestViewModelet le DTO de l’API.

  2. AjoutezApi:BaseUrldanswwwroot/appsettings.json, enregistrezHttpClientdans leProgram.csdu front-end et remplacezMockLeaveApiparHttpLeaveApi.

  3. ÉcrivezHttpLeaveApi: les cinq méthodes de l’interface et la traduction des erreurs Problem Details enLeaveApiException.

  4. Configurez CORS dans l’API pour la seule origine du front-end, en développement.

  5. Rejouez le parcours complet en français et en anglais, y compris une double approbation et une demande invalide.

  6. Ajoutez Zoé Mendes au jeu de démonstration et constatez l’erreur, puis ajoutezContractTypes.Internship,InternshipPolicyet son enregistrement.

  7. Écrivez deux tests unitaires pourInternshipPolicy, l’un pour un stage en cours, l’autre pour un stage qui n’a pas commencé, et un test d’API pour le solde de Zoé. Lancezdotnet test.

  8. Rédigez le README, puis vérifiez-le en suivant ses instructions dans un clone neuf du dépôt.

Point de contrôle : l’écran affiche les données réelles de l’API dans les deux langues. Le formulaire, l’approbation et le refus fonctionnent, et leurs erreurs s’affichent. Le solde de Zoé vaut0. Tous les tests passent, et le README permet de lancer l’application dans un clone neuf. Enregistrez votre travail avec Git.

En résumé

  • Un front-end et une API indépendants ont chacun leurs classes. Comparez les ViewModels aux DTO avant de les relier : un nom de champ différent ne provoque aucune erreur, seulement une valeur par défaut. En cas d’écart, c’est le client qui s’aligne sur le contrat publié.

  • HttpClientse configure à partir d’une adresse de base lue dans la configuration. Une implémentation HTTP de l’interface attendue par les écrans remplace les données simulées sans toucher aux écrans, et la lecture des réponses Problem Details permet d’afficher à l’utilisateur la vraie raison d’une erreur.

  • CORS est appliqué par le navigateur. Autorisez uniquement l’origine, les verbes et les en-têtes dont votre front-end a besoin, et déclarez l’origine dans la configuration. Côté API, renvoyez des codes et des nombres plutôt que des libellés formatés, pour laisser la vue gérer la langue.

  • Avec Strategy et le conteneur, un nouveau type de contrat s’ajoute avec une constante, une classe, une ligne et des tests, sans modifier le service.

  • Un README court répond aux questions de la prochaine personne et renvoie vers les sources qui restent à jour : OpenAPI, fichier.httpet tests.

Hamac est corrigée, prête à accueillir les stagiaires, et assez lisible pour que Tomás la reprenne sans vous : l’objectif fixé par Inès au premier chapitre est atteint. Il vous reste à vérifier que vous savez appliquer ces réflexes ailleurs que dans Hamac. C’est l’objet du quiz final, qui vous place dans un nouveau contexte.

Ever considered an OpenClassrooms diploma?
  • Up to 100% of your training program funded
  • Flexible start date
  • Career-focused projects
  • Individual mentoring
Find the training program and funding option that suits you best