Minimal APIs compared with MVC
Minimal APIs define endpoints with a few lines in Program.cs instead of controller classes. This lesson shows the same products API written the minimal way, how to organize endpoints as an app grows, and how to choose between minimal APIs and controllers.
- Minimal APIsSmall JSON services, less code, fast startup
- API controllersLarge APIs organized in classes with filters
- MVC controllersWebsites with Razor views
- Mix bothAn MVC site with a few minimal endpoints
Endpoints as functions
Each endpoint is a route plus a handler. Parameters come from the route, query, body or dependency injection, just as with controllers.
var products = app.MapGroup("/api/products").WithTags("Products");
products.MapGet("/", async (ShopContext db, int page = 1) =>
await db.Products.OrderBy(p => p.Id).Skip((page - 1) * 20).Take(20)
.Select(p => new ProductDto(p.Id, p.Name, p.Price)).ToListAsync());
products.MapGet("/{id:int}", async Task<Results<Ok<ProductDto>, NotFound>> (int id, ShopContext db) =>
await db.Products.FindAsync(id) is { } p
? TypedResults.Ok(new ProductDto(p.Id, p.Name, p.Price))
: TypedResults.NotFound());
products.MapPost("/", async (CreateProduct input, ShopContext db) =>
{
var p = new Product { Name = input.Name, Price = input.Price };
db.Products.Add(p);
await db.SaveChangesAsync();
return TypedResults.Created($"/api/products/{p.Id}", new ProductDto(p.Id, p.Name, p.Price));
})
.RequireAuthorization("Admin");Organizing a bigger API
Move each group into an extension method in its own file so Program.cs stays short.
public static class ProductEndpoints
{
public static RouteGroupBuilder MapProductEndpoints(this IEndpointRouteBuilder app)
{
var g = app.MapGroup("/api/products").WithTags("Products");
g.MapGet("/", ListAsync);
g.MapGet("/{id:int}", GetAsync);
return g;
}
static async Task<Ok<List<ProductDto>>> ListAsync(ShopContext db) => TypedResults.Ok(await db.Products.Select(p => new ProductDto(p.Id, p.Name, p.Price)).ToListAsync());
static async Task<Results<Ok<ProductDto>, NotFound>> GetAsync(int id, ShopContext db) =>
await db.Products.FindAsync(id) is { } p ? TypedResults.Ok(new ProductDto(p.Id, p.Name, p.Price)) : TypedResults.NotFound();
}
// Program.cs
app.MapProductEndpoints();Choosing
- Minimal APIs: less ceremony, slightly faster, great for small services and JSON APIs. Validation of data annotations is built in from .NET 10; earlier versions need a filter or library.
- Controllers: familiar structure, filters, model binding conventions and views. Best when the app is an MVC site with pages, or the team prefers classes.
- They mix well: an MVC site can expose a few minimal API endpoints for JavaScript.
- TypedResults make return types explicit, which helps OpenAPI and unit tests.
Interview question
When would you choose minimal APIs over MVC controllers?
Minimal APIs fit small services, microservices and JSON-only endpoints where less ceremony and slightly better performance matter. Controllers fit larger apps that already use MVC views, rely on filters and conventions, or where the team prefers organizing endpoints into classes. Both run on the same routing and middleware and can be used in the same app.
Want the full details? Read the official Microsoft documentation for this topic.