TL;DR: Controllers and Minimal APIs can build the same APIs in .NET (Microsoft’s developer platform), including .NET 8. Controllers give you built-in structure for large, long-lived projects, while Minimal APIs give you lean, endpoint-first code. Choose by team and maintenance needs, since either style can call our eSignature API and receive its events.
You are starting a new web API in .NET. One of the first choices is how to write the endpoints: as controllers or as Minimal APIs.
This C# minimal API vs controllers guide compares both styles in ASP.NET Core, the .NET web framework named after Active Server Pages (ASP). You get side-by-side code, what each style does by default, and a quick way to decide.
Minimal API vs controllers: what is the difference?
The minimal API vs controller based API difference is where your endpoint code lives. Controllers group actions in classes, and Minimal APIs map each route straight to a function.
What are controllers in .NET 8 Web API terms?
Controllers are classes that derive from ControllerBase, with one method per action. They run inside the Model-View-Controller (MVC) pipeline, described in Microsoft Learn’s Web API documentation.
The pipeline adds these parts for you:
- Controller discovery, so the app finds new controllers on start-up
- Model binding conventions for route, query and body values
- MVC filters that run before and after each action
- Action results such as
Ok()andNotFound()
What are Minimal APIs in .NET 8 terms?
Minimal APIs map each route straight to a handler with MapGet, MapPost and similar methods. They use the same ASP.NET Core building blocks as controllers.
Those building blocks include hosting, routing, dependency injection (DI), authentication and middleware. You compose them per endpoint or per route group, in code you read from top to bottom.
How do you decide when to use minimal API vs controller endpoints?
Microsoft recommends Minimal APIs for new projects, citing simpler syntax and less overhead in its APIs overview. Controllers still suit many teams, especially on large APIs.
You make the dotnet minimal API vs controller choice when you create the project. In .NET 8, dotnet new webapi creates a Minimal API project, and dotnet new webapi --use-controllers creates one with controllers.
When should you choose controllers in .NET 8?
Pick controllers when most of these are true:
- You expect many endpoints across several domains or resources.
- You want default conventions for routing, binding and action results.
- You rely on MVC filters and want new developers to find things fast.
- You need custom model binders, application parts or Open Data Protocol (OData) support.
With many endpoints and many contributors, controllers cut down the rules your team has to invent itself.
When should you choose Minimal APIs in .NET 8?
Pick Minimal APIs when most of these are true:
- Your API is a focused service, such as a microservice or an internal API.
- You prefer to set access rules and metadata per endpoint or per route group.
- You will keep handlers thin and group them in feature modules.
- You want per-endpoint checks through endpoint filters.
Commit to structure when you choose Minimal APIs. Minimal should mean less ceremony, not less discipline.
How does a request flow through each style?
Both styles start with routing and end with a result. The steps in between differ.
How does a controller request flow?
A controller request goes from routing to controller selection, then through MVC filters to the action and its result. MVC filters are the built-in extension point at each stage.
How does a Minimal API request flow?
A Minimal API request goes from routing straight to the handler and then to the result. Optional endpoint filters wrap the handler, so they can check its arguments before it runs.
How does the same endpoint look in minimal API vs controller C# code?
Here is one task in both styles: get a widget by its ID, or return 404 when it is missing.
How do you write the endpoint as a controller?
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/widgets")]
public class WidgetsController : ControllerBase
{
private readonly IWidgetService _service;
public WidgetsController(IWidgetService service) => _service = service;
[HttpGet("{id:guid}")]
public async Task<ActionResult<Widget>> Get(Guid id, CancellationToken ct)
{
var widget = await _service.GetAsync(id, ct);
return widget is null ? NotFound() : Ok(widget);
}
}
How do you write the endpoint as a Minimal API?
app.MapGet("/api/min/widgets/{id:guid}", async (
Guid id,
IWidgetService service,
CancellationToken ct) =>
{
var widget = await service.GetAsync(id, ct);
return widget is null ? Results.NotFound() : Results.Ok(widget);
});
Both versions are thin Hypertext Transfer Protocol (HTTP) layers that call a service. Keep them that way, and the choice of style matters less.
How do DI and testability compare between controllers and Minimal APIs?
Both styles use the same DI container, so keep actions and handlers thin either way. ASP.NET Core’s fundamentals apply equally to both.
- Controllers usually take services through constructor injection.
- Minimal API handlers usually take services as handler parameters.
- In both, business logic belongs in services you can test without HTTP.
A simple test of your design: can you unit test the business logic without starting a web server?
How does validation differ in ASP.NET minimal API vs controller endpoints?
Controllers check models for you, while Minimal APIs in .NET 8 leave validation to you. Endpoint filters are the usual place to add it.
How do controllers typically do validation?
Controllers rely on model binding and validation attributes. Many teams also return one error format for every endpoint with Problem Details.
How do Minimal APIs typically enforce validation and consistent errors?
Minimal APIs can run the same checks from an endpoint filter on a route group. The filter below returns Problem Details when the name is empty, so every endpoint in the group fails the same way.
using Microsoft.AspNetCore.Http;
var group = app.MapGroup("/api/min/widgets");
group.MapPost("/", async (CreateWidgetRequest req, IWidgetService service, CancellationToken ct) =>
{
await service.CreateAsync(req.Name, ct);
return Results.Created("/api/min/widgets/...", null);
})
.AddEndpointFilter(async (context, next) =>
{
var req = context.GetArgument<CreateWidgetRequest>(0);
if (string.IsNullOrWhiteSpace(req.Name))
{
return Results.Problem(
title: "Validation failed",
detail: "Name is required.",
statusCode: StatusCodes.Status400BadRequest,
type: "https://www.rfc-editor.org/rfc/rfc9110"
);
}
return await next(context);
});
Client code then has one error shape to handle, whichever endpoint it calls.
From .NET 10, Minimal APIs also have built-in validation. Call AddValidation, and the runtime checks DataAnnotations attributes and returns 400 Bad Request on failure (ASP.NET Core 10 release notes).
What OpenAPI and Swagger setup do both styles need?
Both controllers and Minimal APIs can generate an OpenAPI document in .NET 8. Add this to Program.cs:
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
AddEndpointsApiExplorer()lets the generator find Minimal API endpoints.AddSwaggerGen()builds the OpenAPI document from that endpoint data.UseSwagger()andUseSwaggerUI()serve the document and a test page during development.
AddSwaggerGen and the Swagger user interface (UI) come from the open-source Swashbuckle.AspNetCore package. From .NET 9, Microsoft’s own Microsoft.AspNetCore.OpenApi package can generate the document too.
Controllers describe their endpoints through MVC conventions and attributes. Minimal APIs describe theirs through calls on each endpoint, so you add a little more metadata by hand.
How does authorization differ in ASP.NET Core minimal API vs controller code?
The authorization system underneath is the same, and only the syntax differs. Microsoft’s authorization overview covers both.
- Controllers use the
[Authorize]attribute on a class or an action. - Minimal APIs call
.RequireAuthorization()on an endpoint or a route group. - Both read the same policies you register at start-up.
Set policy at the highest sensible level, such as the controller or the route group. Then override it only where an endpoint needs something different.
What does [ApiController] automatically do that Minimal APIs do not?
With [ApiController] on a controller, ASP.NET Core turns on several behaviors by default. The Web API documentation lists them:
- Every action needs attribute routing.
- An invalid model gets an automatic 400 Bad Request response.
- Validation errors come back in the Problem Details format.
- Binding sources such as
[FromBody]and[FromRoute]are inferred. - Error results of 400 and above get a Problem Details body.
For example:
[ApiController]
[Route("api/widgets")]
public class WidgetsController : ControllerBase
{
[HttpPost]
public IActionResult Create(CreateWidgetRequest request)
{
// If ModelState is invalid,
// framework automatically returns 400 with ProblemDetails
return Ok();
}
}
Minimal APIs in .NET 8 validate a model only when you add the check yourself. You can do it in one of these ways:
- Validate by hand inside the handler.
- Add an endpoint filter.
- Use a validation library or custom middleware.
Controllers give you these rules by default. Minimal APIs ask you to apply them on purpose.
What are the performance differences between minimal API and traditional ASP.NET Core controllers?
Minimal APIs carry less framework overhead than controllers, and Microsoft lists better performance as one reason to start with them. In many real APIs, though, most time goes to database calls, network calls and serialization.
Minimal APIs also support native ahead-of-time (AOT) compilation in .NET 8, and MVC controllers do not (Native AOT support). Native AOT can cut start-up time, memory use and container image size.
Measure before you switch styles for speed. Check your median and slowest response times, and count your database round trips.
How do you keep Minimal APIs maintainable as the codebase grows?
Keep Program.cs for wiring, and map endpoints in one feature module per area. Each module is a static class with an extension method, as in this example.
public static class WidgetEndpoints
{
public static RouteGroupBuilder MapWidgetEndpoints(this IEndpointRouteBuilder app)
{
var group = app.MapGroup("/api/min/widgets")
.RequireAuthorization();
group.MapGet("/{id:guid}", GetById);
group.MapPost("/", Create);
return group;
}
private static async Task<IResult> GetById(Guid id, IWidgetService service, CancellationToken ct)
=> (await service.GetAsync(id, ct)) is { } w ? Results.Ok(w) : Results.NotFound();
// Return a Location header that points to the new widget
private static async Task<IResult> Create(CreateWidgetRequest req, IWidgetService service, CancellationToken ct)
{
var id = await service.CreateAsync(req.Name, ct);
return Results.Created($"/api/min/widgets/{id}", null);
}
}
Every widget endpoint now lives in one file. You can find them all without scrolling through Program.cs.
How can you make Minimal APIs production-grade in large codebases?
Treat structure as part of the job from the first endpoint. Group your habits into two sets: how you organize endpoints and how you keep their behavior consistent.
How do you organize the endpoints?
- Use one route group per feature.
- Move each group’s mappings into a feature module.
- Apply authorization at the group level.
How do you keep endpoint behavior consistent?
- Use endpoint filters the same way across groups.
- Handle errors in one central place.
- Return the same response types from every endpoint.
The module pattern from the last section, trimmed to its mapping method, looks like this:
public static class WidgetEndpoints
{
public static RouteGroupBuilder MapWidgetEndpoints(this IEndpointRouteBuilder app)
{
var group = app.MapGroup("/api/min/widgets")
.RequireAuthorization();
group.MapGet("/{id:guid}", GetById);
group.MapPost("/", Create);
return group;
}
}
A healthy structure passes one simple test. You can locate all widget endpoints without searching Program.cs.
Which approach fits common scenarios?
Use this table as a starting point, then weigh your team’s habits.
| Scenario | Suggested approach |
|---|---|
| Large enterprise API | Controllers |
| Many teams contributing | Controllers |
| Heavy use of MVC filters | Controllers |
| Strict governance rules | Controllers |
| Small microservice | Minimal APIs |
| Focused internal API | Minimal APIs |
| Per-endpoint setup preferred | Minimal APIs |
| Lean edge service | Minimal APIs |
Both styles can build any of these. The real question is whether you want structure by default or structure you compose yourself.
How does this choice fit a BoldSign API integration?
Our eSignature API can send webhook events to your app when a document is signed or completed, as our developer documentation describes. Either style can receive them.
A small Minimal API endpoint suits a service that only handles these events. Add a controller action instead when your app already uses controllers.
Which BoldSign plan do you need to use the API, and what does it cost?
Live calls to the BoldSign API need the Enterprise API plan, which starts at $30 a month with 40 envelopes. Each extra envelope costs $0.75, as listed on the BoldSign pricing page in November 2026.
Prices are in USD. Webhooks come with the Enterprise API plan, and the free sandbox lets you build and test before you go live.
Where do you go next after choosing controllers vs minimal API?
Start new services in the style that fits your team, and keep handlers thin either way. Then test your endpoints against a real API.
- Create a free API sandbox account and send a test document from your endpoint.
- Request a demo to talk through your integration with our team.
- Visit our support portal with a question about your setup.
Frequently asked questions
Should I pick a controller vs minimal API for a new .NET 8 project?
Microsoft recommends Minimal APIs for new projects. Pick controllers when you need what they give out of the box, such as custom model binders, application parts or OData support.
Minimal APIs vs controllers .NET: which should a beginner learn first?
Start with Minimal APIs, since a working endpoint takes only a few lines in Program.cs. Learn controllers next, because many existing codebases use them.
Is a Minimal API still a representational state transfer (REST) API?
It can be. REST is a set of design rules, and Minimal APIs are one way to write the code. Microsoft's Web API design guide is a good starting point for the design side.
Do Minimal APIs support OpenAPI and Swagger?
Yes. Both styles can produce an OpenAPI document in .NET 8, as the Minimal APIs overview shows. The Swagger test page comes from the open-source Swashbuckle.AspNetCore package.
Are endpoint filters the same as MVC filters?
They do similar jobs, such as validation and logging, but they run in different pipelines. You can still add an endpoint filter to controller actions when both styles need the same logic.
Can you use controllers and Minimal APIs in the same app?
Yes. One ASP.NET Core app can map controller routes and Minimal API routes side by side. Both share the same routing, dependency injection and middleware.
Does .NET 8 validate Minimal API requests automatically?
In .NET 8, you add validation yourself in the handler, in an endpoint filter or with a library. From .NET 10, calling AddValidation turns on built-in checks for DataAnnotations attributes.
Should you migrate existing controllers to Minimal APIs in .NET 8?
Only with a clear reason, such as a better fit for your endpoints or a simpler structure. Profile your API first, and skip a migration made only for speed.