> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/asp.net-core-web-api-standards/minimal-apis-vs-controllers.md).

# 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

```csharp
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

```csharp
[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