What Are Minimal APIs?
Minimal APIs, introduced in .NET 6, let you define HTTP endpoints directly against a WebApplication instance using methods like MapGet and MapPost, without requiring a Controller class, action methods, or the MVC conventions that route requests through reflection-based discovery. A handler is just a delegate, often a lambda, that ASP.NET Core invokes when the route matches, making minimal APIs well suited to small services, microservices, and prototypes where the ceremony of a full MVC controller isn't justified.
Cricket analogy: Minimal APIs are like T20 cricket compared to a five-day Test match such as an Ashes fixture: you skip the elaborate rituals of a Test (new-ball ceremonies, five days of setup) and get straight to bowling overs and scoring runs, just as MapGet skips controller ceremony to handle a request.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderService, OrderService>();
var app = builder.Build();
app.MapGet("/orders/{id:int}", async (int id, IOrderService orders) =>
{
var order = await orders.GetByIdAsync(id);
return order is not null ? Results.Ok(order) : Results.NotFound();
});
app.MapPost("/orders", async (CreateOrderRequest request, IOrderService orders) =>
{
var created = await orders.CreateAsync(request);
return Results.Created($"/orders/{created.Id}", created);
});
app.Run();Routing and Endpoint Handlers
Endpoint handlers are registered with MapGet, MapPost, MapPut, and MapDelete, each taking a route template and a delegate. Route parameters can carry type constraints, such as {id:int}, which are checked during route matching itself: a request whose id segment isn't a valid integer simply won't match that route, rather than reaching the handler and failing later during binding.
Cricket analogy: Routing endpoints to methods is like assigning a bowler to a specific over in an ODI: MapGet('/players/{id:int}', ...) is as precise as telling Jasprit Bumrah he bowls over 47, with the {id:int} constraint acting like the umpire rejecting a no-ball before it's even bowled.
Route parameter constraints like {id:int}, {id:guid}, or {slug:alpha} are checked at match time. A request to /orders/abc against a MapGet("/orders/{id:int}", ...) route simply won't match, falling through to the next candidate route (or a 404) instead of reaching the handler and failing binding there.
Dependency Injection in Minimal APIs
Handler parameters are resolved from the application's dependency injection container exactly as they are for MVC controllers: declaring a parameter typed as a registered interface, like IOrderService, causes ASP.NET Core to resolve the concrete implementation automatically before invoking the handler. This means services, DbContext instances, and configuration objects registered in Program.cs are available to minimal API handlers with no additional wiring.
Cricket analogy: It's like a captain such as Rohit Sharma automatically getting the right specialist bowler handed to him for a given match situation: a handler parameter of type IOrderService is 'handed the ball' by the DI container the moment the over (request) begins, no manual selection needed.
Filters and Middleware Considerations
Cross-cutting concerns like input validation, logging, or short-circuiting invalid requests are handled through endpoint filters, registered with .AddEndpointFilter() on a mapped route. A filter runs around the handler's invocation and can inspect or modify the request, short-circuit it entirely by returning a result without calling the handler, or transform the response on the way out, filling a role similar to MVC action filters but scoped per-endpoint.
Cricket analogy: Endpoint filters are like a third-umpire review that runs before a decision is finalized: .AddEndpointFilter() lets you intercept a request before the handler 'bowls', similar to how DRS checks a delivery for a no-ball before the wicket counts.
Minimal APIs don't automatically apply [ApiController]-style conventions such as automatic 400 responses on invalid model state, and they infer binding sources differently (complex types default to the body, simple types default to the query string). Porting an MVC controller to minimal APIs without re-checking these inference rules can silently change behavior.
- Minimal APIs define endpoints directly on a WebApplication using MapGet, MapPost, MapPut, and MapDelete, without requiring a controller class.
- Route parameters can carry type constraints like {id:int} that reject non-matching requests before the handler ever runs.
- Handler parameters are resolved from the DI container automatically; the same services registered for MVC controllers work here too.
- Endpoint filters, added with AddEndpointFilter, let you validate or short-circuit a request before or after the handler executes.
- Minimal APIs don't inherit MVC's [ApiController] conventions automatically, so automatic model-state validation must be handled explicitly.
- Complex-type parameters bind from the request body by default; simple types bind from the query string by default.
- Minimal APIs are well suited to small services and focused endpoints where a full controller class would be unnecessary ceremony.
Practice what you learned
1. Which method registers a minimal API endpoint that responds to HTTP GET requests?
2. In a minimal API handler, how are services registered in the DI container typically supplied to the handler?
3. What does the route constraint in app.MapGet("/orders/{id:int}", ...) do?
4. How do you intercept and potentially short-circuit a minimal API request before the handler executes?
5. By default, how does a minimal API handler infer the binding source for a complex type parameter (like a DTO class)?
Was this page helpful?
You May Also Like
Controllers and Attribute Routing
How ControllerBase classes and [Route]/[Http*] attributes map incoming requests to action methods in ASP.NET Core Web API.
Model Binding and Validation
How ASP.NET Core maps incoming request data onto action parameters and validates it before your handler code runs.
Action Results and Status Codes
How ASP.NET Core action results map to HTTP status codes, and how to choose the right response for every outcome.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics