Minimal APIs in .NET Are Not a Toy, Start Treating Them That Way

When Minimal APIs landed in .NET 6, a lot of developers dismissed them. "That's for demos," they said. "Real APIs use controllers."

Two major .NET versions later, I think that take has aged badly. Minimal APIs aren't a stripped-down shortcut they're a deliberate design choice, and when used correctly, they produce cleaner, faster, and more maintainable code than the controller approach. But you have to actually use them correctly.

Let me show you what that looks like.

The Setup That Doesn't Embarrass You in Code Review

Everyone's seen the "hello world" version of Minimal APIs:

var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run();

Cool. Now forget it. Nobody ships that.

Here's a foundation that scales:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.MapOrderEndpoints();

app.Run();

That MapOrderEndpoints() call is where the real structure lives. We'll get there in a second.

Stop Putting Everything in Program.cs

This is the mistake that gives Minimal APIs a bad reputation. People dump 300 lines of endpoint definitions into Program.cs and then complain that it's unreadable. That's not the framework's fault.

The pattern that actually works is extension methods per feature:

// Endpoints/OrderEndpoints.cs
public static class OrderEndpoints
{
    public static void MapOrderEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/orders")
                       .WithTags("Orders")
                       .RequireAuthorization();

        group.MapGet("/", GetAllOrders);
        group.MapGet("/{id:int}", GetOrderById);
        group.MapPost("/", CreateOrder);
        group.MapPut("/{id:int}", UpdateOrder);
        group.MapDelete("/{id:int}", DeleteOrder);
    }

    private static async Task<IResult> GetAllOrders(
        IOrderService service, CancellationToken ct)
    {
        var orders = await service.GetAllAsync(ct);
        return Results.Ok(orders);
    }

    private static async Task<IResult> GetOrderById(
        int id, IOrderService service, CancellationToken ct)
    {
        var order = await service.GetByIdAsync(id, ct);
        return order is null ? Results.NotFound() : Results.Ok(order);
    }

    private static async Task<IResult> CreateOrder(
        CreateOrderRequest request, IOrderService service, CancellationToken ct)
    {
        var created = await service.CreateAsync(request, ct);
        return Results.CreatedAtRoute("GetOrderById", new { id = created.Id }, created);
    }

    // ... UpdateOrder, DeleteOrder follow the same pattern
}

One file per feature. Each file owns its routes, its handlers, its grouping. Program.cs stays clean. This is what maintainable looks like.

Route Groups Are Underused

MapGroup was added in .NET 7 and I still see people not using it. It lets you apply common configuration prefixes, auth, rate limiting, tags to a set of routes in one place instead of repeating it on every MapGet.

var api = app.MapGroup("/api/v1")
             .RequireAuthorization()
             .AddEndpointFilter<RequestLoggingFilter>();

var orders = api.MapGroup("/orders").WithTags("Orders");
var products = api.MapGroup("/products").WithTags("Products");

Now everything under /api/v1 requires auth and gets logged, without you touching each individual endpoint. When you add a new route to the group, it inherits everything automatically. That's the kind of thing that saves you from a bug where someone forgets to add .RequireAuthorization() to a new endpoint.

Validation Without the Ceremony

One legitimate criticism of Minimal APIs is that validation isn't as automatic as it is with controllers and [ApiController]. You have to handle it explicitly. Fine explicit is better than magic you can't find when something breaks.

Here's a clean approach using an endpoint filter:

public class ValidationFilter<T> : IEndpointFilter
{
    private readonly IValidator<T> _validator;

    public ValidationFilter(IValidator<T> validator)
    {
        _validator = validator;
    }

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var argument = ctx.Arguments.OfType<T>().FirstOrDefault();

        if (argument is not null)
        {
            var result = await _validator.ValidateAsync(argument);
            if (!result.IsValid)
                return Results.ValidationProblem(result.ToDictionary());
        }

        return await next(ctx);
    }
}

Attach it to any endpoint that takes a request body:

group.MapPost("/", CreateOrder)
     .AddEndpointFilter<ValidationFilter<CreateOrderRequest>>();

This uses FluentValidation, but the pattern works with any validation library. The point is: the filter runs before your handler, you return a proper ValidationProblem response, and your handler stays clean. No if (!ModelState.IsValid) noise inside every method.

TypedResults Over Results Always

You've probably seen both of these:

// Untyped
return Results.Ok(order);

// Typed
return TypedResults.Ok(order);

The difference isn't just aesthetics. TypedResults preserves the response type in the method signature, which means Swagger/OpenAPI can infer your response types without you manually decorating everything with Produces<T>().

private static async Task<Results<Ok<Order>, NotFound>> GetOrderById(
    int id, IOrderService service, CancellationToken ct)
{
    var order = await service.GetByIdAsync(id, ct);
    return order is null ? TypedResults.NotFound() : TypedResults.Ok(order);
}

That return type is self-documenting. The OpenAPI spec knows this endpoint returns either a 200 with an Order or a 404 — automatically, no attributes needed. Use TypedResults from day one on any project you care about.

Error Handling: One Place, Not Everywhere

Don't try-catch inside every handler. That's controller thinking leaking into Minimal APIs.

.NET 8 introduced IProblemDetailsService and the built-in exception handler middleware that pairs cleanly with Minimal APIs:

app.UseExceptionHandler(errApp =>
{
    errApp.Run(async ctx =>
    {
        var ex = ctx.Features.Get<IExceptionHandlerFeature>()?.Error;

        var problem = ex switch
        {
            NotFoundException => new ProblemDetails
            {
                Status = 404,
                Title = "Not Found",
                Detail = ex.Message
            },
            ValidationException => new ProblemDetails
            {
                Status = 400,
                Title = "Validation Failed",
                Detail = ex.Message
            },
            _ => new ProblemDetails
            {
                Status = 500,
                Title = "Server Error",
                Detail = "Something went wrong."
            }
        };

        ctx.Response.StatusCode = problem.Status ?? 500;
        await ctx.Response.WriteAsJsonAsync(problem);
    });
});

One place handles all unhandled exceptions. Your handlers throw, the middleware catches. Clean separation.

Performance: This Is Where Minimal APIs Win

It's not even close. Minimal APIs have measurably lower overhead than MVC controllers because they skip a lot of the pipeline — action filters, model binding infrastructure, the full MVC middleware stack.

In the TechEmpower benchmarks, ASP.NET Core with Minimal APIs consistently ranks among the fastest web frameworks across all languages. This isn't theoretical. If you're building high-throughput services, the choice matters.

That said — don't pick Minimal APIs only for performance if your team is deeply comfortable with controllers. The best architecture is the one your team can actually maintain. But if you're starting fresh, there's no reason to reach for the heavier option.

When to Stick With Controllers

I'd be doing you a disservice if I didn't say this: controllers still make sense in some situations.

Large teams where convention-based structure reduces decision fatigue
Legacy codebases where mixing patterns adds confusion
Heavy use of action filters and model binding customization that MVC handles better out of the box

Minimal APIs aren't the answer to every problem. They're the right tool for services where you want explicit, lightweight, testable endpoints — which is most of what I build these days.

The Bottom Line

Minimal APIs hit their stride in .NET 7 and .NET 8. The feature gaps that made people hesitant — proper grouping, filters, typed results, auth integration — are closed. What's left is a leaner, faster, more explicit alternative to controllers that scales fine as long as you structure it properly.

Stop putting everything in Program.cs. Use route groups. Use TypedResults. Handle errors in one place. Keep your handlers small and your services doing the actual work.

That's it. That's a clean Minimal API.

推荐订阅源

DEV Community