ASP.NET Core Minimal APIs vs Controllers
On this page
Learning Objective
Build the same endpoint with minimal APIs and with controllers, describe the trade-offs between the styles, organize a growing API into route groups, and apply authorization by default so that forgetting to secure an endpoint is not an option.
Concept Explanation
ASP.NET Core offers two ways to define HTTP endpoints. Controllers are classes whose public methods, decorated with attributes such as HttpGet and Route, handle requests. This is the older style, familiar to anyone who has seen Spring or Angular's decorator-heavy code. Minimal APIs, introduced in .NET 6, define endpoints as lambdas or methods registered with MapGet, MapPost and similar calls, which reads much like an Express or Fastify route. Both run on the same pipeline, both support dependency injection, authorization, filters, and OpenAPI, and you can mix them in one application.
Controllers give you more conventions out of the box. The ApiController attribute infers where parameters come from and automatically returns a 400 response when model validation fails. Filters provide a structured way to apply cross-cutting behavior, and large teams often like the predictable one-class-per-resource layout. Minimal APIs give you less ceremony and slightly better startup and per-request performance, and they encourage small, focused handlers. For a frontend developer moving to the backend, minimal APIs are usually the fastest route to something working, and in .NET 10 they gained built-in validation support that closes the largest historic gap.
The recommendation in this course is minimal APIs organized by feature. Instead of one giant Program.cs, put each feature's endpoints in a static class with a Map method, and attach them to the application using route groups. A group applies a shared route prefix, tags, filters, and requirements, such as authentication, to every endpoint inside it. That leads directly to the most important habit of this lesson: make security the default and public access the exception. Set a fallback authorization policy that requires an authenticated user for every endpoint that does not say otherwise, and mark the few public ones, such as health checks and login, with AllowAnonymous.
This is not stylistic. One of the most common ways an API leaks data is that a developer adds an endpoint and forgets the authorization attribute, so it is open to the world without anyone noticing. Secure-by-default inverts the failure mode: forgetting the annotation now produces a 401 that a test catches immediately, rather than a silent exposure discovered in a penetration test. The same reasoning applies if you choose controllers, where you can add a global authorization filter or set the same fallback policy.
| Aspect | Minimal APIs | Controllers |
|---|---|---|
| Definition | MapGet, MapPost with lambdas or methods | Classes with attribute-routed action methods |
| Boilerplate | Low | More |
| Conventions | Explicit, you opt in | Many by default via ApiController |
| Grouping | MapGroup with shared rules | Controller class and base routes |
| Cross-cutting behavior | Endpoint filters, middleware | Action filters, middleware |
| Best for | Small to mid services, feature-oriented layout | Large teams that value strict convention |
Worked Example: One Endpoint Two Ways, Then a Secure Group
The first two blocks implement the same read endpoint. The last block shows a feature module using a route group and a fallback policy so everything is authenticated unless declared public.
// Minimal API style
app.MapGet("/api/notes/{id:int}", async (int id, NotesDb db) =>
await db.Notes.FindAsync(id) is { } note ? Results.Ok(note) : Results.NotFound());
// Controller style
[ApiController]
[Route("api/notes")]
public class NotesController(NotesDb db) : ControllerBase
{
[HttpGet("{id:int}")]
public async Task<ActionResult<Note>> Get(int id) =>
await db.Notes.FindAsync(id) is { } note ? note : NotFound();
}// Program.cs: secure by default.
builder.Services.AddAuthorizationBuilder()
.SetFallbackPolicy(new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build()); // every endpoint requires sign-in unless opted out
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/health", () => Results.Ok("ok")).AllowAnonymous(); // deliberate exception
app.MapNotesEndpoints();
app.Run();
// NotesEndpoints.cs: one file per feature.
public static class NotesEndpoints
{
public static void MapNotesEndpoints(this IEndpointRouteBuilder app)
{
var group = app.MapGroup("/api/notes").WithTags("Notes");
group.MapGet("/", ListAsync);
group.MapGet("/{id:int}", GetAsync);
group.MapPost("/", CreateAsync);
}
static async Task<IResult> GetAsync(int id, NotesDb db) =>
await db.Notes.FindAsync(id) is { } note ? TypedResults.Ok(note) : TypedResults.NotFound();
static async Task<IResult> ListAsync(NotesDb db) => TypedResults.Ok(await db.Notes.ToListAsync());
static async Task<IResult> CreateAsync(CreateNote body, NotesDb db)
{
var note = new Note { Title = body.Title };
db.Notes.Add(note);
await db.SaveChangesAsync();
return TypedResults.Created($"/api/notes/{note.Id}", note);
}
}The group's prefix and tags apply to every endpoint in it. Because of the fallback policy, none of the three note endpoints is reachable without a signed-in user even though no attribute says so, and the health check shows what an intentional exception looks like. This example still returns entities directly, which Day 23 will correct.
Real-World Examples
- Minimal APIs arrived in .NET 6 in November 2021 and were designed partly in response to how quickly developers could stand up a service in Node.js frameworks like Express. Microsoft has since invested heavily in them, and the default web API template in current SDK versions uses the minimal style.
- The ApiController attribute, which controllers use, adds behaviors such as automatic HTTP 400 responses when model state is invalid, binding source inference, and problem details for error results. Teams migrating to minimal APIs often find they must consciously add equivalents, which is one reason .NET 10's built-in validation support matters.
Review Questions & Answers
It applies shared configuration to every endpoint inside it, including the route prefix, OpenAPI tags, endpoint filters, and requirements such as RequireAuthorization or a rate limit policy. That makes cross-cutting rules a single declaration that new endpoints inherit automatically, instead of a checklist developers must remember on each one.
It requires an authenticated user for any endpoint that has no explicit authorization metadata, so a newly added endpoint is protected without anyone doing anything. Public endpoints must be marked deliberately with AllowAnonymous, which makes them visible in code review. The failure mode changes from an accidental public endpoint to a loud 401 that tests catch.
When they value strong conventions across a large team, rely on existing controller-based filters and libraries, or are extending a large existing codebase that already uses controllers. Nothing prevents mixing the two in one application, so there is no need to rewrite a working controller-based API just to adopt minimal APIs for new features.
Nothing observable. Both produce the same HTTP 404 response, because both go through the same response-writing machinery in the framework. The style you choose affects how the server code is organized, not the wire contract, which is why React does not care how the backend defines its routes.