C# Web API - Un regard complet sur la structuration des API avec l'approche de Derek Comartin

Examen des structures d'API communes

Derek commence par poser la question que se posent la plupart des développeurs lorsqu'ils créent un nouveau projet d'API Web dans Visual Studio :

"Comment devez-vous structurer votre API HTTP ?"

Il reconnaît d'emblée que les projets d'API Web peuvent être organisés de différentes manières. Parmi les structures de dossiers les plus courantes, Derek voit :

• Regroupement par préoccupations techniques - mettre les modèles dans un dossier Models, les contrôleurs dans un dossier Controllers et les services dans Services.

• Utilisation de l'architecture propre ou de l'architecture en oignon - où les projets sont divisés par couches (API, application, domaine, infrastructure) pour guider les dépendances.

• Combinaison de la conception pilotée par le domaine (DDD) et de l'architecture en tranches verticales - regroupement des points d'extrémité par fonction tout en conservant des objets riches en contenu.

Derek souligne que chacun de ces modèles permet de créer une API RESTful qui utilise les méthodes HTTP habituelles (GET, POST, PUT, DELETE) pour travailler avec des ressources. Il met toutefois en garde contre une interprétation trop poussée des seules structures de dossiers :

"Vous pouvez voir des entités, des agrégats ou des services de domaine, mais cela ne signifie pas que le code fait vraiment de la conception orientée domaine - il utilise simplement ces modèles."

Partir de la simplicité, pas de la complexité

Derek explique que son objectif est simple :

"L'une des principales choses que je voulais réaliser avec cette structure est la simplicité."

Plutôt que de se lancer dans une architecture lourde de type .NET Framework ou de reproduire des modèles tirés de manuels, Derek choisit ASP.NET Core Minimal APIs. Pourquoi ? Parce qu'ils facilitent la création d'API sans les contraintes liées aux contrôleurs et au code de base.

Lorsque vous créez un nouveau projet d'API Web dans Visual Studio ou même Visual Studio Code, il se peut que vous commenciez par la boîte de dialogue Nouveau projet et que vous sélectionniez ASP.NET Core Web API. Par défaut, vous disposerez de contrôleurs, de dossiers et d'un grand nombre d'échafaudages. Derek affirme qu'il est souvent préférable de commencer plus petit - une structure simple et propre.

La structure de base de l'API Web de Derek

Derek présente la structure de son application web en utilisant .NET Core. Il est conçu pour prendre en charge les services HTTP courants et les API RESTful qui permettent à différentes applications logicielles de communiquer.

Voici comment il organise son projet d'API web :

• Endpoints File - Un fichier unique pour voir toutes les routes disponibles dans l'API. Au lieu de fouiller dans plusieurs contrôleurs, Derek veut une vue d'ensemble rapide de chaque méthode get, méthode post, requête put ou requête delete que l'API prend en charge.

• Dossier commun - Contient le code partagé, comme les filtres et les extensions, utilisé par différents systèmes logiciels.

• Dossiers de fonctionnalités - Conformément à la philosophie de la tranche verticale, chaque nouvelle ressource ou ressource existante reçoit son propre dossier. Par exemple, un dossier Posts peut inclure tout ce qui est nécessaire pour GET /posts/{id}, POST /posts, PUT /posts/{id} et DELETE /posts/{id}.

• Dossier de données - Contient le modèle de données et les mappages d'entités. Ici, Entity Framework Core peut être utilisé pour une intégration transparente des bases de données.

En regroupant les points de terminaison par fonction, Derek évite de disperser la logique dans plusieurs dossiers sans rapport entre eux.

Pourquoi il n'impose pas la conception pilotée par les domaines

Derek a déjà utilisé la conception pilotée par les domaines par le passé, mais dans cette structure d'API Web C#, il fait un choix clé :

"Nous n'allons pas utiliser la conception pilotée par le domaine"

Au lieu de cela, il "laisse les données être les données" Ses modèles de données sont de simples classes dotées de propriétés simples telles que :

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

Aucun comportement superflu ne doit être intégré. Lorsque vous envoyez une requête POST pour créer une nouvelle ressource, l'API l'enregistre simplement. Lorsque vous envoyez une requête DELETE avec un paramètre id, cette ressource est supprimée.

Cette approche adopte le style architectural du Representational State Transfer (REST) en traitant les points d'extrémité de l'API comme des verbes (méthode get, méthode post, méthode put, méthode delete) agissant sur des ressources telles que Post, User ou Comment.

Parcourir la solution dans Visual Studio

À ce stade, Derek ouvre sa solution Visual Studio et nous fait visiter les lieux :

• Le fichier Endpoints répertorie toutes les routes, qu'il s'agisse d'une requête GET pour récupérer des données, d'une requête POST pour ajouter une nouvelle ressource, d'une requête PUT pour mettre à jour des données ou d'une méthode DELETE pour supprimer une ressource existante.

• Le dossier Data contient des mappages pour des entités telles que Post, User et Comment, connectées à une base de données via Entity Framework.

• Le dossier Common contient la logique partagée pour les services HTTP tels que les filtres de validation et les extensions.

• Chaque dossier de fonctionnalité (messages, commentaires, authentification) contient tout le code nécessaire pour cette ressource.

Cette présentation claire du dossier de projet évite de devoir fouiller dans une boîte de dialogue de projet trop complexe ou dans un dossier de contrôleurs éparpillé.

Décomposer un point de terminaison

Derek explique que chaque point de terminaison de son API Web ASP.NET Core est une unité de travail autonome comportant trois étapes claires :

1. Mapping - Définit la méthode et la route HTTP. Par exemple, une demande de suppression peut faire correspondre DELETE /posts/{id} à une méthode de traitement.

2. Contrats de requête et de réponse - Chaque point d'accès a son propre corps de requête et son propre type de réponse. Cela rend les services HTTP plus clairs et évite de créer des couches de DTO en double.

3. Logique - La méthode de traitement proprement dite, dans laquelle l'API extrait des données de la base de données, met à jour un modèle de données ou renvoie un code d'état tel que return CreatedAtAction ou return NoContent.

Derek utilisant des API minimales, ces gestionnaires sont des méthodes statiques. Avec ASP.NET Core, cela signifie que vous pouvez injecter des dépendances directement - aucune classe de contrôleur encombrante n'est nécessaire.

Pourquoi les API minimales se sentent bien

Derek fait l'éloge des API minimales pour leur simplicité. Grâce au modèle minimal d'ASP.NET Core, vous pouvez démarrer un projet d'API web avec seulement quelques lignes dans Program.cs :

var app = WebApplication.CreateBuilder(args).Build();

var app = WebApplication.CreateBuilder(args).Build();

À partir de là, vous ajoutez vos méthodes get, post et put de manière simple.

Cette simplicité permet d'éviter la sur-ingénierie - quelque chose que Derek voit trop souvent lorsque les développeurs copient aveuglément des modèles de paquets nuget ou forcent de nouvelles classes de contrôleurs pour chaque point de terminaison mineur.

Comment la complexité peut évoluer dans le temps

Derek donne un exemple concret : la fonction "aimer un article".

• Au début, c'est simple : vérifier si un like existe, en ajouter un si ce n'est pas le cas.

• Mais plus tard, l'application logicielle pourrait avoir besoin de renvoyer un compte similaire instantanément pour les pages web ou les appareils mobiles.

• Pour mettre les données à l'échelle, vous pouvez les dénormaliser en ajoutant une propriété LikeCount au modèle de données Post.

De nouveaux défis se présentent :

• Chaque méthode de mise en place ou de suppression qui affecte les likes doit correctement mettre à jour le décompte.

• Si quelqu'un ajoute un enregistrement similaire sans appeler l'API, le décompte est erroné.

Derek montre qu'au fur et à mesure que la complexité augmente, vous pouvez ajouter des modèles tels que :

• Modèle de référentiel pour encapsuler l'accès aux données.

• Aggregate roots to handle behaviors (like incrementing LikeCount) (racines agrégées pour gérer les comportements (comme l'incrémentation de LikeCount).

• Modèle de boîte d'envoi pour garantir la publication des événements (comme "PostLiked").

Mais son point essentiel est clair :

"Ne commencez pas ici. Commencez par du simple et n'évoluez que si nécessaire."

Terminer avec les conclusions de Derek

Derek termine en revenant sur sa principale leçon destinée aux développeurs d'API Web C# :

"Commencez par le plus simple"

Lorsque vous utilisez ASP.NET Core Web API ou ASP.NET Web API dans Visual Studio, il est facile de sur-ingénierie dès le premier jour - en ajoutant tous les dossiers, modèles et packages NuGet que vous avez jamais vus.

Mais Derek met en garde : n'appliquez pas les solutions aveuglément. Comprenez les méthodes HTTP dont vous avez besoin, les données avec lesquelles vous travaillez et les systèmes logiciels entre lesquels vous permettez la communication. Créez vos API RESTful étape par étape.

Pour ceux qui utilisent Visual Studio Code ou tout autre environnement de développement intégré, ses conseils sont valables : Qu'il s'agisse d'un nouveau projet ou d'une ressource existante, gardez la structure de votre projet aussi simple que possible et n'ajoutez des modèles que lorsque la complexité du monde réel l'exige.

Conclusion

La vidéo de Derek Comartin est plus qu'un simple guide pour la création d'une API Web en C#, c'est un rappel qu'une bonne architecture commence par la clarté, et non par l'encombrement. En parcourant sa configuration réelle de l'API Web ASP.NET Core dans Visual Studio, il montre comment les API minimales, les dossiers de fonctionnalités et les modèles de données simples peuvent constituer la base des API RESTful qui permettent une communication transparente entre différentes applications logicielles sans compliquer excessivement la conception.

Si vous souhaitez voir cette approche en action et entendre le point de vue de Derek, sa vidéo est une excellente ressource. Son canal est rempli de discussions tout aussi perspicaces sur les systèmes logiciels, les services web et le développement ASP.NET Core - un must à suivre pour tout développeur cherchant à améliorer son art et à garder ses projets propres, pratiques et adaptés à l'avenir.