DEV Community: shayan holakouee

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

shayan holakouee — Sun, 26 Apr 2026 19:49:25 +0000

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.

You're Probably Using async/await Wrong (And It's Costing You)

shayan holakouee — Sun, 26 Apr 2026 19:45:04 +0000

Let me be direct: most .NET developers I've seen , including myself, early on — treat async/await like a magic sprinkle. Slap it on a method, everything becomes non-blocking, ship it. Done.

Except it's not done. And the bugs that come from that mindset are the worst kind: the ones that only show up under load, in production, at 2am.

This article isn't an intro. I'm assuming you know what Task is and that you've written at least one async method before. What I want to do is get into the stuff that actually matters when you're building something real.

The Myth of "Just Add async"

Here's a pattern I see constantly:

public async Task<List<Order>> GetOrdersAsync()
{
    var orders = _db.Orders.ToList(); // synchronous, blocking
    return orders;
}

This method is async in name only. It doesn't await anything. The compiler will actually warn you about this — and then generate a state machine that wraps a synchronous operation for absolutely no benefit. You've added overhead without gaining anything.

If there's no genuine I/O or CPU-bound work to await, don't use async. Simple. Return Task.FromResult(value) if the interface demands it.

async void Is a Trap

// Don't do this
public async void LoadData()
{
    var data = await _service.FetchAsync();
    Display(data);
}

async void methods cannot be awaited. Exceptions thrown inside them will crash the process — they're not catchable from outside. The only legitimate use case is event handlers, and even then, I'd argue you should immediately delegate to an async Task method and keep the void shell as thin as possible.

private async void Button_Click(object sender, EventArgs e)
{
    await LoadDataAsync(); // delegate immediately
}

private async Task LoadDataAsync()
{
    var data = await _service.FetchAsync();
    Display(data);
}

This way you have a testable, awaitable, exception-safe path.

ConfigureAwait(false): Know When It Matters

You've probably seen this:

var result = await _httpClient.GetAsync(url).ConfigureAwait(false);

Here's what's actually happening. By default, await captures the current SynchronizationContext and resumes on it. In a UI app, that means resuming on the UI thread. In ASP.NET (pre-Core), it meant resuming on the request context thread.

.ConfigureAwait(false) tells the runtime: "I don't care which thread I resume on." This avoids a deadlock-prone pattern and removes the overhead of re-capturing the context.

Rule of thumb:

Library code? Always use .ConfigureAwait(false). You don't know what context your callers are in.
Application-level code (controllers, view models, UI handlers)? Skip it — you usually do care about the context.

ASP.NET Core doesn't have a SynchronizationContext the same way, so deadlocks from missing ConfigureAwait(false) are less common there. But the performance argument for library code still stands.

The Classic Deadlock (And Why It Still Happens)

// This will deadlock in certain contexts
public string GetData()
{
    return _service.GetDataAsync().Result; // blocking on async
}

Calling .Result or .Wait() on an async Task in a context with a SynchronizationContext is asking for trouble. The await inside GetDataAsync() tries to resume on the original context, but you're blocking that context waiting for the Task to finish. Stalemate.

The fix is: go async all the way. Async is infectious by design. Once you start, you have to follow through up the call chain. If you're finding yourself reaching for .Result to "escape" the async world, that's a sign something higher up in your design needs to change.

Parallelism vs. Concurrency — They're Not the Same Thing

This distinction matters a lot and gets blurred constantly.

Concurrency is about dealing with multiple things at once. Parallelism is about doing multiple things at once. async/await gives you concurrency; it doesn't automatically give you parallelism.

If you need to fire off three independent HTTP calls and wait for all of them:

// Concurrent — all three start immediately, not sequentially
var t1 = _client.GetAsync("/orders");
var t2 = _client.GetAsync("/products");
var t3 = _client.GetAsync("/users");

var results = await Task.WhenAll(t1, t2, t3);

Compare this to:

// Sequential — each waits for the previous
var r1 = await _client.GetAsync("/orders");
var r2 = await _client.GetAsync("/products");
var r3 = await _client.GetAsync("/users");

Same end result. Radically different performance. The first version is what you want when the calls are independent.

For CPU-bound work (image processing, heavy computation), use Task.Run to push it off the thread pool:

var result = await Task.Run(() => HeavyCpuWork(data));

Don't use Task.Run for I/O-bound work. That's what truly async APIs are for. Task.Run hands the work to a thread pool thread, which still blocks a thread. Truly async I/O doesn't block any thread at all while waiting.

CancellationToken: Stop Ignoring It

public async Task<Report> GenerateReportAsync(CancellationToken ct = default)
{
    var rawData = await _db.GetRawDataAsync(ct);
    ct.ThrowIfCancellationRequested();
    var processed = await ProcessAsync(rawData, ct);
    return BuildReport(processed);
}

If your async methods don't accept and propagate a CancellationToken, you are leaking resources. A user cancels a request, navigates away, or the server needs to shut down — without cancellation support, you're still chewing through CPU and I/O doing work for nobody.

Propagate the token everywhere you can. Pass it to every I/O method that accepts one. Add ct.ThrowIfCancellationRequested() at logical checkpoints in long operations.

In ASP.NET Core, the CancellationToken is built into HttpContext — just accept it as a method parameter in your controllers and the framework will wire it up automatically.

When Things Go Wrong: Exception Handling in Tasks

Task.WhenAll collects exceptions from all tasks. If multiple fail, you only see the first one by default:

try
{
    await Task.WhenAll(t1, t2, t3);
}
catch (Exception ex)
{
    // Only the first exception
}

To inspect all failures:

var allTasks = Task.WhenAll(t1, t2, t3);
try
{
    await allTasks;
}
catch
{
    if (allTasks.Exception != null)
    {
        foreach (var inner in allTasks.Exception.InnerExceptions)
        {
            // handle each
        }
    }
}

It's verbose, but it's the correct way to handle partial failures in a parallel batch.

One More Thing: Don't Over-Async

Not everything needs to be async. A pure in-memory calculation, a simple property lookup, a fast synchronous transformation — adding async overhead to these things doesn't make them faster. It makes them slower, with more allocations and state machine noise.

Async shines when you're waiting on something external: a database, an HTTP call, a file, a message queue. That's the domain. Stay in it.

Wrapping Up

async/await in .NET is genuinely one of the best concurrency models in any mainstream language. But "best" doesn't mean "foolproof." The foot-guns are real: async void, blocking on tasks, ignoring cancellation, confusing concurrency with parallelism.

Get these right and your async code becomes a superpower. Get them wrong and you get subtle, nasty bugs that only show up when it matters most.

Go refactor something.