Minimal API ASP.NET Core - Le guide pour bien les utiliser

Dans ASP.NET Core, le modèle de minimal API permet de construire un backend HTTP avec très peu de code, sans perdre les bases utiles comme le routage, le binding des paramètres, l’injection de dépendances et les réponses typées. Je vais montrer ce que cette approche change réellement, quand elle est pertinente, comment l’écrire proprement et à partir de quel moment elle devient moins confortable qu’une API à contrôleurs. L’intérêt est simple: aller vite au départ sans créer un futur chantier de refonte.

Ce qu’une API minimaliste change dans ASP.NET Core

Je vois cette approche comme une façon de composer une application autour de deux objets centraux: WebApplicationBuilder pour préparer l’environnement, puis WebApplication pour déclarer les routes et lancer le serveur. Au lieu d’une couche de contrôleurs, d’attributs et de conventions MVC plus lourdes, on travaille avec des route handlers, c’est-à-dire des fonctions qui reçoivent une requête et renvoient directement une réponse HTTP.

Le gain n’est pas seulement esthétique. On lit le chemin d’une requête beaucoup plus vite, on comprend plus facilement ce qui se passe, et on garde une surface de code réduite tant que le domaine métier reste simple. Dans un service qui expose quelques opérations CRUD, un endpoint d’état, une recherche et deux ou trois intégrations, cette sobriété est souvent un vrai avantage. Le point important, c’est que le minimalisme porte sur la forme du code, pas sur les capacités du framework.

Autrement dit, je ne parle pas d’une API “allégée” au sens fragile du terme, mais d’une API qui s’appuie sur moins d’abstraction pour atteindre le même objectif HTTP. La vraie question devient alors: est-ce que cette simplicité vous fait gagner du temps sans vous en faire perdre plus tard? C’est ce que j’examine juste après.

Les gains réels que l’on voit dès le premier projet

Quand une équipe démarre un backend, elle cherche souvent trois choses: livrer vite, garder le code lisible et ne pas multiplier les fichiers inutiles. C’est là que l’approche minimaliste fait la différence. La plupart des endpoints tiennent dans quelques lignes, l’onboarding est plus rapide, et l’on peut faire évoluer le service par petites itérations sans traverser tout un maillage de classes.

La liste des bénéfices utiles est assez stable dans la pratique:

• Moins de boilerplate pour déclarer les routes et les réponses HTTP.
• Lecture plus directe quand un endpoint reste simple et qu’il n’y a pas beaucoup de logique partagée.
• Prototype plus rapide si l’on valide un produit, une intégration ou un flux métier.
• Surface mentale réduite pour les petites équipes qui veulent se concentrer sur le domaine plutôt que sur la structure.
• Exposition claire des dépendances grâce à l’injection et au binding déjà intégrés.

Je l’utilise volontiers pour des services internes, des backends orientés BFF, des microservices, ou des API qui servent surtout de passerelle vers un stockage, une file de messages ou un autre système. Dans ces cas-là, la sobriété du code aide vraiment. Et si le projet prend de l’ampleur, on peut encore conserver la même base tout en ajoutant de la structure; c’est précisément ce qu’il faut préparer dans la suite.

Écrire une première route propre sans surcharger `Program.cs`

Le piège classique consiste à croire que “minimal” signifie “tout mettre dans un seul fichier”. Je préfère une approche un peu plus stricte: garder Program.cs comme point d’assemblage, puis déplacer la logique de domaine ou les groupes d’endpoints dès que le fichier commence à gonfler. Le code reste simple, mais il ne devient pas confus.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApi();

var app = builder.Build();

var todos = new List();

app.MapGet("/todos/{id:int}", (int id) =>
{
    var todo = todos.FirstOrDefault(t => t.Id == id);
    return todo is null ? Results.NotFound() : TypedResults.Ok(todo);
});

app.MapPost("/todos", (TodoInput input) =>
{
    var todo = new Todo(todos.Count + 1, input.Title, false);
    todos.Add(todo);

    return TypedResults.Created($"/todos/{todo.Id}", todo);
});

app.Run();

record Todo(int Id, string Title, bool IsDone);
record TodoInput(string Title);

Dans cet exemple, on voit bien la logique de fond: la route, les paramètres et la réponse sont visibles immédiatement. Le TypedResults aide à garder des réponses cohérentes et améliore la description OpenAPI, ce qui devient très utile dès qu’un front, un client mobile ou un autre service consomme l’API. Le binding des paramètres est lui aussi central: route, query string, corps JSON ou services injectés, tout cela reste disponible sans mécanisme exotique.

Ce type de départ convient très bien tant que les handlers restent courts et que la logique métier ne déborde pas partout. Dès que les cas d’usage se diversifient, il faut comparer cette approche aux contrôleurs pour éviter de forcer un modèle au mauvais endroit.

Comparer l’approche aux contrôleurs pour éviter le mauvais choix

Je ne présente pas les contrôleurs comme un “ancien monde” à abandonner. Ils restent souvent plus confortables dès qu’un backend accumule de la validation, des conventions, de la versioning, des comportements transversaux et des dépendances multiples. La bonne décision dépend moins d’une préférence idéologique que de la forme réelle du projet.

Mon critère de terrain est assez simple: si l’application sert surtout à exposer du HTTP, la solution minimaliste est souvent la meilleure base; si elle commence à ressembler à une plateforme métier dense, les contrôleurs reprennent vite de la valeur. Le choix se fait donc moins sur le mot “minimal” que sur la quantité de règles que le projet doit porter.

Les règles d’organisation qui gardent le code lisible

Une API sobre ne reste lisible que si l’on met quelques garde-fous en place dès le début. Le premier, c’est le regroupement des routes par domaine avec MapGroup: on évite ainsi de répéter les préfixes, les métadonnées et les contraintes partout. Le deuxième, c’est de limiter le rôle de Program.cs à la composition, pas à la logique métier.

Je recommande aussi de penser en “modules” plutôt qu’en fichiers accumulés au hasard. Chaque ensemble de routes peut vivre dans une extension dédiée, une classe de configuration ou un fichier par fonctionnalité. Cela garde la lecture simple sans sacrifier la clarté du domaine.

Les filtres d’endpoint méritent aussi une place dans votre boîte à outils. Ils permettent d’exécuter du code avant ou après un handler, de valider une requête, de journaliser un comportement ou d’intercepter une réponse. En pratique, c’est très utile pour centraliser ce qui se répète trop souvent: validation légère, contrôle de format, vérification d’un contrat métier ou gestion de quelques règles communes.

• Je regroupe les endpoints par ressource ou par cas d’usage, pas par hasard chronologique.
• Je garde les handlers courts et explicites, avec un vrai nom de fonction si la logique dépasse quelques lignes.
• Je déplace les règles transversales dans des filtres ou dans des services dédiés.
• Je mets l’OpenAPI, les tags et les autorisations au niveau du groupe quand c’est pertinent.
• Je teste les routes critiques avec des tests d’intégration, pas seulement avec des tests unitaires isolés.

Avec cette discipline, l’approche reste légère sans devenir brouillonne. Et c’est justement là que se jouent les erreurs les plus courantes, celles qui transforment une bonne idée en dette technique inutile.

Les pièges que je surveille avant de mettre en production

Le premier piège est presque toujours le même: tout laisser dans un seul fichier parce que le démarrage a été simple. Ce choix finit par coûter cher dès que le code grossit, car la lisibilité baisse plus vite que prévu. Le deuxième piège est la validation dispersée, avec les mêmes vérifications réécrites d’un endpoint à l’autre.

Je vois aussi régulièrement des projets qui négligent les réponses typées. Résultat: les contrats deviennent flous, l’OpenAPI perd en qualité et les clients consomment une API moins prévisible. Quand on travaille avec du JSON, cette prévisibilité est pourtant l’un des vrais atouts du framework.

Enfin, il ne faut pas oublier la partie production: authentification, autorisation, journalisation, gestion d’erreurs et tests d’intégration. Une API minimaliste n’est pas moins sérieuse qu’une API à contrôleurs, mais elle laisse davantage de liberté au développeur. Cette liberté est utile seulement si elle s’accompagne d’un minimum de méthode.

• Ne pas confondre “peu de code” et “pas de structure”.
• Ne pas multiplier les lambdas anonymes quand un vrai handler nommé clarifie mieux le flux.
• Ne pas reporter la validation à plus tard sous prétexte que l’API est petite.
• Ne pas ignorer les tests d’intégration sur les routes sensibles.
• Ne pas laisser la sécurité devenir un ajout de dernière minute.

Une fois ces points verrouillés, le choix d’architecture devient beaucoup plus net. Il reste alors à trancher selon le type de backend que l’on veut réellement construire.

Mon filtre de décision avant de lancer un backend

Quand je dois décider rapidement, je me pose quatre questions simples. Si la réponse est “oui” à la majorité d’entre elles, j’opte sans hésiter pour une API minimaliste. Sinon, je préfère poser une structure plus proche des contrôleurs ou au moins organiser le projet comme s’il allait grandir vite.

• Le service expose-t-il surtout des routes HTTP simples avec peu de logique de présentation?
• Le domaine métier est-il assez clair pour être découpé par modules sans surcharge de conventions?
• L’équipe peut-elle maintenir des règles d’organisation explicites dès le départ?
• Les besoins d’autorisation, de validation et de versioning restent-ils raisonnables à court terme?

Si ces conditions sont réunies, je privilégie la simplicité de composition et la vitesse d’exécution. Si elles ne le sont pas, je préfère une structure plus explicite plutôt que de compenser plus tard par des rustines. C’est souvent la meilleure manière d’éviter le faux débat entre “moderne” et “classique”, et de choisir à la place ce qui restera lisible dans six mois.