[Intermediate] · Two endpoint styles in one framework — what differs, what doesn’t, and which to pick.

Both are ASP.NET Core. Same pipeline, same DI, same routing engine. They differ in how you declare an endpoint, not in what happens underneath.

Minimal APIs

app.MapGet("/orders/{id:int}", async (int id, IOrderService svc) =>
        await svc.GetAsync(id) is { } order
            ? Results.Ok(order)
            : Results.NotFound())
   .WithName("GetOrder")
   .Produces<Order>()
   .RequireAuthorization();
 
app.MapPost("/orders", async (CreateOrder cmd, IOrderService svc) =>
{
    var created = await svc.CreateAsync(cmd);
    return Results.Created($"/orders/{created.Id}", created);
});

Parameters are resolved by convention: route values by name, complex types from the JSON body, registered services from DI, and [FromQuery]/[FromHeader] when you need to be explicit.

Route constraints ({id:int}) are matching rules, not validation — /orders/abc produces a 404, not a 400, because the route simply didn’t match.

Controllers (MVC)

[ApiController]
[Route("api/[controller]")]
public class OrdersController(IOrderService svc) : ControllerBase
{
    [HttpGet("{id:int}")]
    [ProducesResponseType<Order>(StatusCodes.Status200OK)]
    public async Task<ActionResult<Order>> Get(int id)
        => await svc.GetAsync(id) is { } order ? Ok(order) : NotFound();
}

[ApiController] is doing real work — automatic model-state validation returning a 400 with ProblemDetails, inference of binding sources, and attribute routing requirements. Without it you’d hand-write if (!ModelState.IsValid) in every action.

Which to use

Minimal APIsControllers
CeremonyLowHigher
DiscoverabilityEndpoints scattered unless you organiseGrouped by class
Filters / conventionsEndpoint filtersMature, richer
Native AOTSupportedLimited
Views / RazorNoYes
Large teamsNeeds disciplineStructure comes free

The pragmatic answer: Minimal APIs for new services, small APIs and anything targeting AOT. Controllers for large APIs where the class structure is genuine organisation, and for anything server-rendered.

Minimal APIs are not “for small apps”. They scale fine — but you must impose the structure. MapGroup is the tool:

var orders = app.MapGroup("/orders").RequireAuthorization().WithTags("Orders");
orders.MapGet("/{id:int}", GetOrder);
orders.MapPost("/", CreateOrder);

Put handlers in separate static classes and register them per feature, or you get a 900-line Program.cs — which is the real failure mode → structuring a backend.

Validation

Neither style validates a request body by itself beyond type binding.

  • Controllers + [ApiController] — DataAnnotations ([Required], [Range]) are checked automatically
  • Minimal APIs — nothing built in until recently. FluentValidation is the common answer
public class CreateOrderValidator : AbstractValidator<CreateOrder>
{
    public CreateOrderValidator()
    {
        RuleFor(x => x.Quantity).GreaterThan(0).LessThanOrEqualTo(100);
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
    }
}

Validate at the boundary — the same argument as Pydantic in FastAPI and zod in TypeScript. Type annotations describe intent; only a validator enforces it at runtime → note 02.

Errors → status codes

builder.Services.AddProblemDetails();
app.UseExceptionHandler();

ProblemDetails (RFC 9457) is the standardised error body, and ASP.NET Core produces it by default. Use it rather than inventing a shape → API design.

Map domain exceptions to status codes in one place — an IExceptionHandler or an exception-handling middleware — rather than try/catch in every endpoint. Never let a raw stack trace reach a client in production → DevSecOps.

OpenAPI

.NET 9+ ships built-in OpenAPI document generation (AddOpenApi/MapOpenApi); Swashbuckle and NSwag remain common and offer more.

The honest comparison with FastAPI: there, the schema is derived from the same Pydantic model that validates — so drift between docs and behaviour is structurally impossible. In ASP.NET Core the schema is generated from types and attributes, and can drift from a separately-defined validator. Worth knowing rather than assuming parity.

The concept translation

Course conceptASP.NET Core
ControllerMapGet handler, or a ControllerBase action
ServiceYour class, registered in DI
RepositoryYour class, or DbContext directly
Middlewareapp.Use… / endpoint filters
DIBuilt in
ValidationDataAnnotations or FluentValidation
Errors → statusProblemDetails + IExceptionHandler

Source: [reference] — from the ASP.NET Core documentation, Aug 2026.

↑ Back to C# Backends — ASP.NET Core