ASP.NET Core controllers - API controller mechanics

This skill owns the shape of a controller-based Web API: how a controller is declared, how routes attach, what an action returns, how parameters bind, and how a cross-cutting concern hangs off an action. It is the mainstream, brownfield-friendly counterpart to dotnet-minimal-api - the same HTTP service, sliced into classes and methods instead of endpoint registrations. It stops at the controller boundary. The pipeline-wide concerns - validation library, OpenAPI document, resilience, observability, caching - live in dotnet-web-backend. The failure-to-ProblemDetails contract and the FluentValidation filter are dotnet-error-handling. Auth configuration is dotnet-authentication. Floor is .NET 8 / C# 12; anything newer is marked optional. On .NET Framework 4.8 (MVC 5 / Web API 2) the two separate DI resolvers and the bind-DTOs-not-entities rule are in references/net-framework-48.md.

When to reach for controllers over minimal APIs is a deliberate call - see the decision section at the end. The short version: greenfield prefers minimal APIs; controllers earn their place when an existing codebase, MVC views, or a convention-driven feature (OData, attribute-based API versioning) calls for them.

The controller and the [ApiController] attribute

An API controller is a class deriving from ControllerBase (not Controller - that base drags in view support you do not want on a pure API) and decorated with [ApiController]: