Controllers vs Minimal APIs: Stop Picking a Winner

The debate between Controllers and Minimal APIs in .NET 10 does not revolve around which one is superior. Instead, the focus should be on selecting the shape that best suits the API being developed. Once the decision is made, the subsequent steps are crucial. The actual tradeoff is as follows:

Controllers (MVC) are better for large APIs, convention-heavy teams, edge cases in model binding, existing MVC codebases, and framework integration (such as ABP, OData). Minimal APIs are ideal for small/medium services, vertical slices, high-throughput endpoints, and AOT scenarios. Controllers offer attribute routing and conventions, while Minimal APIs utilize explicit Map* calls. Controllers have a slightly higher overhead per request and carry the lowest risk.

One of the primary risks for both approaches is the tendency for the codebase to become unwieldy, with both Controllers and Minimal APIs potentially accruing logic or Map* calls in a single location. The key is to prevent either approach from turning into a dumping ground, rather than deciding which style to start with.

For Minimal APIs, avoid stacking endpoints directly in Program.cs. Instead, organize them as modules through an extension method, such as:

```csharp

public static class PostEndpoints {

public static IEndpointRouteBuilder MapPosts(this IEndpointRouteBuilder app) {

var group = app.MapGroup("/api/posts")

.WithTags("Posts")

.RequireAuthorization()

.AddEndpointFilter(ValidationFilter);

// Add more endpoint mappings here

return app;

}

}

app.MapPosts();

```

This approach keeps Program.cs lean, with one line per feature. For Controllers, the discipline involves keeping them thin and focused on a single job: translating an HTTP request into a call on another component. Important practices include:

- Controllers should be thin, with actions binding the request, delegating to a service, and shaping the response.

- Avoid handling EF queries or business rules within controller actions; these should be in separate services.

- Always include [ApiController], which provides automatic 400 responses on model-binding failures and infers binding sources.

- Never return raw entities; instead, return IActionResult or TypedResults and shape the response explicitly.

- Always accept and forward CancellationToken, and avoid async void, .Result, and .Wait() to prevent thread-pool starvation and deadlock issues.