With .NET 6, Microsoft introduced Minimal APIs, a lightweight way to build HTTP APIs with far less ceremony than traditional ASP.NET MVC or Web API. The idea is simple: write less boilerplate, focus more on behavior.
Minimal APIs are not a replacement for MVC in every scenario—but they shine in many modern use cases like microservices, lightweight backends, and rapid prototypes.
Let’s break down what they are, why they matter, and when you should (or shouldn’t) use them.
What Are Minimal APIs?
Minimal APIs allow you to define HTTP endpoints directly in Program.cs without controllers, attributes, or complex routing structures.
Instead of this:
[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult Get(int id)
{
return Ok($"User {id}");
}
}
You can write this:
var app = WebApplication.CreateBuilder(args).Build();
app.MapGet("/users/{id}", (int id) =>
{
return Results.Ok($"User {id}");
});
app.Run();
Same result. Much less code.
Why Minimal APIs Exist
Traditional ASP.NET APIs are powerful, but they come with overhead:
- Controllers
- Attributes
- Filters
- Startup configuration
- Inheritance-heavy design
Minimal APIs were created to:
- Reduce ceremony
- Improve startup performance
- Simplify microservices
- Make APIs easier to reason about
They follow a function-first approach instead of a class-first one.
Key Features of Minimal APIs
1. Minimal Boilerplate
No controllers. No attributes. No base classes.
Endpoints are defined inline:
app.MapPost("/login", (LoginRequest request) =>
{
return Results.Ok();
});
This is especially useful for small services or internal APIs.
2. Built-in Dependency Injection
You can inject services directly into endpoint parameters.
app.MapGet("/products", (IProductService service) =>
{
return service.GetAll();
});
No constructor injection needed.
3. Automatic Model Binding
Minimal APIs support:
- Route values
- Query strings
- Headers
- Body binding
app.MapPost("/users", (UserDto user) =>
{
return Results.Created($"/users/{user.Id}", user);
});
4. Validation Support
With DataAnnotations and IEndpointFilter, you can still validate input.
app.MapPost("/register", (RegisterModel model) =>
{
return Results.Ok();
})
.AddEndpointFilter<ValidationFilter>();
This keeps validation explicit and composable.
5. Built-in Result Helpers
Minimal APIs encourage explicit HTTP responses:
return Results.NotFound();
return Results.BadRequest("Invalid input");
return Results.Ok(data);
This makes response behavior crystal clear.
6. Middleware Friendly
Minimal APIs work seamlessly with middleware:
app.UseAuthentication();
app.UseAuthorization();
You don’t lose any ASP.NET Core power.
Authentication and Authorization
Authorization can be applied per endpoint:
app.MapGet("/admin", () => "Admin area")
.RequireAuthorization("AdminPolicy");
This is often clearer than attribute-based security.
OpenAPI and Swagger Support
Minimal APIs fully support Swagger:
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
Swagger UI works exactly as it does with controllers.
When Minimal APIs Are a Great Fit
Minimal APIs work best when:
- Building microservices
- Creating internal APIs
- Writing small to medium services
- Prototyping quickly
- Hosting serverless APIs
- Building BFF (Backend for Frontend) layers
They are fast, clean, and easy to maintain in these cases.
When MVC or Controllers Are Better
Minimal APIs are not ideal when:
- You have very large APIs with hundreds of endpoints
- You rely heavily on filters, action results, and conventions
- You prefer strict separation of concerns
- Your team is deeply invested in MVC patterns
Controllers still provide structure and familiarity for complex enterprise systems.
Minimal API Project Structure (Recommended)
Even though endpoints are “minimal”, your architecture shouldn’t be.
A clean structure looks like:
/Endpoints
└── UserEndpoints.cs
/Services
└── UserService.cs
/Models
└── UserDto.cs
Program.cs
Example:
public static class UserEndpoints
{
public static void MapUserEndpoints(this WebApplication app)
{
app.MapGet("/users", GetUsers);
}
private static IResult GetUsers(IUserService service)
=> Results.Ok(service.GetAll());
}
This keeps your code maintainable as it grows.
Performance Benefits
Minimal APIs:
- Have faster startup times
- Use fewer abstractions
- Reduce memory allocations
This makes them especially attractive for cloud-native and high-scale systems.
Final Thoughts
Minimal APIs are not “toy APIs” or shortcuts. They are a first-class API model in modern .NET.
Think of them as:
- Simple when small
- Structured when needed
- Powerful without the ceremony
If you’re building modern APIs in .NET 6+ and haven’t tried Minimal APIs yet—you’re missing out on a cleaner, faster way to ship backend services.
