Minimal APIs vs Controllers — When to Choose Which

MVC Controllers:
  Endpoint declared as class method
  Route: [HttpGet("{id}")] attribute
  Auth: [Authorize(Policy = "...")] attribute
  DI: constructor injection
  Filters: [ServiceFilter(typeof(MyFilter))] attribute
  Framework: action invoker pipeline, ModelState, IActionResult

Minimal APIs:
  Endpoint declared as delegate (lambda or method reference)
  Route: app.MapGet("{id}", handler)
  Auth: .RequireAuthorization("...")
  DI: parameter injection
  Filters: .AddEndpointFilter()
  Framework: lighter pipeline, IResult

Minimal API overhead per request: ~10-20% less than controllers
Why: No action invoker, no ControllerBase allocation, lighter pipeline

In practice:
  If your API processes 1,000 req/sec:
    20% savings = 200 req/sec improvement — significant
  If your API processes 10 req/sec:
    20% savings = 2 req/sec improvement — irrelevant

Recommendation: choose Minimal API for high-throughput APIs where
every millisecond matters. Choose controllers when productivity
and familiarity matter more than peak throughput.

// Controller action test — requires full controller instantiation
public class PatientControllerTests
{
    [Fact]
    public async Task GetPatient_should_return_ok()
    {
        var controller = new PatientController(
            Substitute.For<IGetPatientHandler>());
        controller.ControllerContext = new ControllerContext
        {
            HttpContext = new DefaultHttpContext()
        };

        var result = await controller.GetPatient(Guid.NewGuid(), CancellationToken.None);
        result.Should().BeOfType<OkObjectResult>();
    }
}

// Minimal API handler test — just call the delegate
[Fact]
public async Task GetPatient_handler_should_return_not_found_for_unknown_id()
{
    var handler = Substitute.For<IGetPatientHandler>();
    handler.Handle(Arg.Any<GetPatientQuery>(), Arg.Any<CancellationToken>())
           .Returns(Result.Failure<PatientDto>(PatientErrors.NotFound));

    // Call the handler function directly — no HTTP context needed
    var result = await PatientEndpoints.GetPatient(
        Guid.NewGuid(), handler, CancellationToken.None);

    result.Should().BeOfType<NotFound>();
}

// Both work — WebApplicationFactory tests are equivalent for both

Minimal APIs — organizing 50+ endpoints:
  ✓ MapGroup for shared prefix and auth
  ✓ Extension methods (MapPatients, MapPrescriptions) split across files
  ✗ No built-in class-level organization
  ✗ Requires discipline to avoid Program.cs bloat

Controllers — organizing 50+ endpoints:
  ✓ Each controller is a class — natural grouping
  ✓ [ApiController] + [Route("api/[controller]")] gives consistent URLs
  ✓ Familiar to every .NET developer
  ✗ Heavier — ControllerBase, ModelState, ActionResult hierarchy
  ✗ Attributes scattered through the file

Feature                  Minimal API         Controller
─────────────────────────────────────────────────────────
Performance              Faster              Slightly slower
Boilerplate              Less                More (class, constructor)
Discoverability          Requires discipline Easy (class browser)
Routing                  Fluent              Attributes
Auth                     .RequireAuthorization [Authorize]
Filters                  .AddEndpointFilter   [ServiceFilter]
Team onboarding          Newer pattern        Universal familiarity
Complex binding          Manual              ModelState auto-binding
File organization        Extension methods    Classes
OpenAPI                  WithOpenApi()        Automatic from attributes

Choose Minimal APIs when:
  ✓ Performance is a top concern (microservices, high-throughput)
  ✓ Starting a new project with a team familiar with Minimal APIs
  ✓ Building a small-to-medium API (under 50 endpoints) where flat organization works
  ✓ You want a clean architecture without MVC's weight

Choose Controllers when:
  ✓ Team is large with developers of varying .NET experience
  ✓ Existing MVC codebase — consistency matters more than performance
  ✓ Complex model binding with ModelState is heavily used
  ✓ Large number of endpoints where class-based organization is clearer
  ✓ You are adding a few endpoints to an existing MVC project

Both are fine:
  Mixing both in one project is supported and common during migration
  Controllers for legacy endpoints; Minimal APIs for new features

// Migrate a controller endpoint to Minimal API incrementally
// Step 1: Controller still exists
[ApiController]
[Route("api/[controller]")]
public class PatientsController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<IActionResult> Get(Guid id, [FromServices] IGetPatientHandler handler)
        => (await handler.Handle(new GetPatientQuery(id), HttpContext.RequestAborted))
           .Match<IActionResult>(dto => Ok(dto), err => err.ToActionResult());
}

// Step 2: Add equivalent Minimal API (test both work)
app.MapGet("/api/patients/{id:guid}", async (
    Guid id, IGetPatientHandler handler, CancellationToken ct) =>
{
    var result = await handler.Handle(new GetPatientQuery(id), ct);
    return result.Match(Results.Ok, err => err.ToProblemResult());
}).RequireAuthorization();

// Step 3: Remove the controller action
// Step 4: Remove the controller class when all endpoints are migrated