Minimal APIs

Minimal APIs were introduced in .NET 6 as a streamlined approach to building HTTP APIs with minimal code and ceremony. They provide a simplified, lightweight alternative to controller-based APIs while maintaining full HTTP functionality.

Core Concepts

Minimal APIs embrace a functional programming style where endpoints are defined directly as lambda expressions or local functions in Program.cs. This approach reduces boilerplate code and provides a more direct path from route to handler.

Key characteristics:

• Reduced ceremony: No need for controller classes, base classes, or attributes for basic routing
• Inline definitions: Routes and handlers defined together in Program.cs
• Performance: Slightly faster startup and potentially lower memory footprint
• Simplicity: Fewer abstractions make the request pipeline more transparent
• Modern C# features: Leverages top-level statements, lambda expressions, and pattern matching

Basic Example

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

app.MapGet("/api/platforms", () => 
{
    // Handler logic here
    return Results.Ok(new { message = "Hello from minimal API" });
});

app.MapPost("/api/platforms", (Platform platform) =>
{
    // Create logic
    return Results.Created($"/api/platforms/{platform.Id}", platform);
});

app.Run();

Differences from Controller-Based APIs

Controllers

Controller-based APIs organize endpoints into classes where each controller represents a resource. They leverage:

• Object-oriented structure: Controllers are classes with methods (actions)
• Convention-based routing: Uses attributes or route templates
• Built-in features: Model binding, validation, filters, and action results
• Organization: Natural grouping of related endpoints

[ApiController]
[Route("api/[controller]")]
public class PlatformsController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<Platform>> GetPlatforms()
    {
        // Handler logic
        return Ok(platforms);
    }
}

Minimal APIs

Minimal APIs define endpoints as individual route registrations:

• Functional structure: Routes defined as functions
• Explicit routing: Each route explicitly mapped
• Direct approach: Less abstraction between route and handler
• Flexibility: Mix and match patterns as needed

app.MapGet("/api/platforms", (IRepository repo) =>
{
    var platforms = repo.GetAll();
    return Results.Ok(platforms);
});

Side by Side

Aspect	Controller-Based APIs	Minimal APIs
Definition Location	Separate controller classes	Program.cs or extension methods
Organization	Grouped by controller classes	Flat or manually organized
Boilerplate Code	More (classes, inheritance, attributes)	Less (direct route mapping)
Learning Curve	Steeper (need to understand MVC pattern)	Gentler (straightforward route definitions)
Best For	Large, complex APIs with many endpoints	Small to medium APIs, microservices
Filters & Middleware	Action filters, controller-level filters	Route filters, endpoint middleware
Model Binding	Automatic with attributes	Automatic via parameters
Testability	Standard unit testing of controller methods	Test handlers as delegates/functions
Scalability	Better organized as complexity grows	Can become unwieldy with many endpoints
Performance	Slightly higher overhead	Marginally faster, lower memory
Code Navigation	Easy (find controller class)	Harder (search through Program.cs)
Dependency Injection	Constructor injection	Parameter injection per route

When to Use Each

Use Controller-Based APIs when:

• Building large APIs with many endpoints
• Team prefers object-oriented organization
• Need extensive use of action filters and complex validation
• Organizational structure is important for maintainability
• Multiple developers working on different controllers

Use Minimal APIs when:

• Building microservices or small focused APIs
• Prioritizing simplicity and reduced boilerplate
• Creating prototypes or proof-of-concepts
• Team is comfortable with functional programming style
• Startup performance is critical

Combining Both Approaches

It's worth noting that controller-based and minimal APIs are not mutually exclusive—you can use both in the same application. This hybrid approach allows you to leverage the organizational benefits of controllers for complex resource groups while using minimal APIs for simple endpoints or health checks.

var builder = WebApplication.CreateBuilder(args);

// Add controller support
builder.Services.AddControllers();

var app = builder.Build();

// Map controllers
app.MapControllers();

// Add minimal API endpoints
app.MapGet("/health", () => Results.Ok("Healthy"));

app.Run();

The choice between controller-based and minimal APIs ultimately depends on your project requirements, team preferences, and architectural goals. Both are fully supported production-ready options in modern .NET.

---

Further Reading:

• Minimal APIs Overview - Microsoft Learn
• Controller-based APIs - Microsoft Learn