← Back to blog

Oct 21, 2026 · 9 min read

ASP.NET Core Minimal APIs: When to Use Them and When to Stick with Controllers

Microsoft now recommends Minimal APIs for new projects. But controllers still have their place. Here's how to decide which approach fits your project.

.NETASP.NET CoreBackend

ASP.NET Core gives you two ways to build HTTP APIs: Minimal APIs and controller-based APIs. Microsoft now recommends Minimal APIs for new projects. But controllers still have their place, and the decision isn't as simple as "new = Minimal, old = controllers."

What Minimal APIs give you

Minimal APIs let you build REST endpoints with minimal code and configuration:

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

app.MapGet("/", () => "Hello World!");
app.MapGet("/users/{id}", (int id) => GetUser(id));
app.MapPost("/users", (User user) => CreateUser(user));

app.Run();

No controller classes, no routing attributes, no scaffolding. You declare routes fluently and move on.

"For new projects, we recommend using Minimal APIs as they provide a simplified, high-performance approach for building APIs with minimal code and configuration." — Microsoft, ASP.NET Core Documentation

The benefits are real:

  • Less boilerplate. A simple API that would take a controller, routing config, and startup registration in the controller model takes a few lines in Minimal APIs.
  • Better performance. Reduced overhead compared to controllers. For high-throughput APIs, this matters.
  • Easier testing. Simpler unit and integration testing because handlers are just functions.
  • Native AOT friendly. Minimal APIs work with the Request Delegate Generator (RDG), which compiles route handlers at build time for Native AOT scenarios.

What controllers give you

Controllers aren't dead. They provide features that Minimal APIs don't have out of the box:

FeatureMinimal APIsControllers
Model binding extensibilityCustom solutionsIModelBinderProvider, IModelBinder
Advanced validationCustom solutionsIModelValidator
Application modelLimitedFull support
ODataNoYes
FiltersMiddlewareBuilt-in
Convention-based routingNoYes

"Most of these features can be implemented in Minimal APIs with custom solutions, but controllers provide them out of the box." — Microsoft, ASP.NET Core Documentation

Performance: does it matter?

BenchmarkDotNet comparisons show Minimal APIs generally outperform controllers in lightweight operations due to reduced overhead. The performance gap narrows as complexity increases.

"Minimal APIs generally outperform Controllers in lightweight operations due to reduced overhead. The performance gap narrows as complexity increases." — Minimal API Performance Benchmark

For a microservice handling thousands of lightweight requests per second, the difference is measurable. For a typical business API with database calls, external service calls, and business logic, the framework overhead is a small fraction of total response time.

How to decide

Choose Minimal APIs if:

  • You're building a new API from scratch
  • You want less boilerplate and faster iteration
  • You're building microservices or high-performance endpoints
  • You want Native AOT support
  • Your team is comfortable with functional-style route handlers

Choose controllers if:

  • You need model binding extensibility (IModelBinderProvider)
  • You need advanced validation features (IModelValidator)
  • You use application parts or the application model
  • You need OData support
  • You have an existing controller-based codebase that's working well

The hybrid approach:

You can use both in the same project. Use Minimal APIs for simple endpoints and controllers for complex ones that need the framework features. This is a legitimate pattern, not a compromise.

Best practices regardless of which you choose

Avoid blocking calls. Don't call Task.Wait or Task.Result. Don't acquire locks in common code paths. Don't call Task.Run and immediately await it — ASP.NET Core already runs app code on thread pool threads.

"Do not block asynchronous execution by calling Task.Wait or Task.Result. Many synchronous blocking calls lead to Thread Pool starvation and degraded response times." — Microsoft, ASP.NET Core Best Practices

Make hot paths asynchronous. Data access, I/O, and long-running operations should use async/await. The entire call stack should be asynchronous to benefit from the pattern.

Don't return large collections all at once. Use pagination, streaming (IAsyncEnumerable), or materialized views to avoid OutOfMemoryException and thread pool starvation.

Use System.Text.Json source generators for Native AOT compatibility and better serialization performance.

The bottom line

For most new projects, Minimal APIs are the right starting point. They're simpler, faster, and the recommended path forward. The features controllers add (model binding extensibility, advanced validation, OData) are real, but most APIs don't need them.

If you're maintaining an existing controller-based codebase that's working well, there's no reason to rewrite it. Controllers are not deprecated. They're a supported, documented part of ASP.NET Core with features that Minimal APIs don't replicate.

The decision is not "which is better?" but "which fits this project?" For a new microservice, Minimal APIs. For a complex API with custom model binding and OData, controllers. For everything in between, start with Minimal APIs and add complexity only when you need it.

Need help applying this?

Schedule call →