API minimales ASP.NET Core vs contrôleurs dans .NET 10

Lorsque vous démarrez une nouvelle API web avec .NET 10, la première bifurcation est aussi l’une des plus déterminantes : Minimal APIs ou contrôleurs ? Les deux sont des citoyens de première classe, entièrement pris en charge, et permettent de construire des services de production sérieux. Le choix ne porte pas sur lequel est « meilleur » dans l’absolu, mais sur celui qui épouse le mieux la forme de votre projet, de votre équipe et la manière dont vous anticipez la croissance du code. Ce guide est un cadre de décision, pas un couronnement : comment chaque modèle fonctionne, là où chacun excelle, et comment choisir sans regret.

Les deux modèles en bref

Les contrôleurs sont l’approche historique de type MVC : les points de terminaison sont des méthodes sur des classes qui héritent d’un contrôleur de base, regroupées par convention, avec des attributs pour le routage et le comportement. Les Minimal APIs, introduites plus récemment et arrivées à maturité, vous permettent de définir les points de terminaison directement comme des gestionnaires de route, généralement des lambdas ou des références de méthode mappées à des routes, avec beaucoup moins de cérémonial et sans hiérarchie de classes imposée.

// Minimal API: the endpoint is the mapping.
app.MapGet("/products/{id:int}", async (int id, IProductService svc) =>
    await svc.Find(id) is { } p ? Results.Ok(p) : Results.NotFound());

// Controller: the endpoint is a method on a class.
[ApiController]
[Route("products")]
public class ProductsController(IProductService svc) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<IActionResult> Get(int id) =>
        await svc.Find(id) is { } p ? Ok(p) : NotFound();
}

Pourquoi l’écart s’est réduit

À leurs débuts, les Minimal APIs étaient véritablement minimales, parfaites pour de petits services, mais il leur manquait des pièces nécessaires à grande échelle, ce qui renvoyait les équipes vers les contrôleurs. Version après version, cet écart s’est comblé. Les Minimal APIs gèrent désormais ce qui était autrefois réservé aux contrôleurs : une liaison de modèle robuste, la validation, le regroupement de points de terminaison liés, les filtres pour les préoccupations transversales et une génération OpenAPI propre. Dans .NET 10, elles constituent un choix par défaut crédible pour des API substantielles, pas seulement pour des jouets.

Là où les Minimal APIs brillent

Là où les contrôleurs conservent leur place

Empêcher les Minimal APIs de devenir un capharnaüm

L’objection la plus courante aux Minimal APIs, « elles ne passent pas à l’échelle pour les grosses applications », est en réalité une objection aux Minimal APIs indisciplinées. La solution, c’est la structure : ne déversez pas tous les points de terminaison dans un seul fichier. Regroupez les points de terminaison liés dans des groupes de routes, extrayez les gestionnaires dans des méthodes nommées ou de petites classes, et enregistrez-les via des méthodes d’extension pour que le démarrage de votre application reste lisible.

// Organise endpoints by feature, registered via extension methods.
public static class ProductEndpoints
{
    public static IEndpointRouteBuilder MapProducts(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/products").WithTags("Products");
        group.MapGet("/{id:int}", GetProduct);
        group.MapPost("/", CreateProduct);
        return group;
    }
    // handlers as named methods, not anonymous lambdas, for testability
}

// Program.cs stays clean:
app.MapProducts();
app.MapOrders();

Le cadre de décision

Vous pouvez même les mélanger

ASP.NET Core permet de faire cohabiter contrôleurs et API minimales dans une même application, ce qui est pratique lors d’une migration progressive ou quand un style convient mieux à une partie de votre application. Utilisez cette possibilité avec parcimonie et de façon réfléchie : une base de code scindée entre deux styles de points de terminaison sans raison claire ne fait que compliquer l’intégration des nouveaux développeurs. Choisissez un modèle principal et faites en sorte que les exceptions restent de véritables exceptions.