Minimal APIs vs Controllers

Purpose

ASP.NET Core supports both Minimal APIs and controller-based APIs. AIC chooses based on complexity, team context and maintainability.

Use Minimal APIs When

• endpoints are simple and focused

• service is small or microservice-like

• low ceremony is valuable

• endpoint grouping is clear

• request handling is straightforward

• source-generated/OpenAPI support is sufficient

Use Controllers When

• API is large or convention-heavy

• filters and attributes simplify cross-cutting concerns

• model binding is complex

• teams expect MVC conventions

• versioning and controller organisation are clearer

• many related actions share policy, route or metadata

AIC Rule

Do not mix Minimal APIs and controllers casually. If both are used, document the reason and partition clearly.

Minimal API Organisation

public static class CaseEndpoints
{
    public static RouteGroupBuilder MapCaseEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/v1/cases")
            .RequireAuthorization("Cases")
            .WithTags("Cases");

        group.MapGet("/{caseId:guid}", GetCaseAsync)
            .WithName("GetCase");

        return group;
    }
}

Controller Organisation

[ApiController]
[Route("api/v{version:apiVersion}/cases")]
public sealed class CasesController : ControllerBase
{
}

Decision Record

For major APIs, record:

• chosen endpoint style

• reason

• expected size

• versioning approach

• testing approach

• OpenAPI approach