Minimal APIs, controllers, routing and binding

// Minimal API
app.MapGet("/orders/{id:int}", async (int id, ShopDb db) =>
    await db.Orders.FindAsync(id) is { } order ? Results.Ok(order) : Results.NotFound());

// Controller
[ApiController]
[Route("orders")]
public class OrdersController(ShopDb db) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<ActionResult<Order>> Get(int id) =>
        await db.Orders.FindAsync(id) is { } order ? order : NotFound();
}

Both sit on the same routing, dependency injection, authentication and authorization. Controllers add MVC filters and the [ApiController] conventions: attribute routing is required, an invalid model returns 400 automatically, and binding sources are inferred. Minimal APIs are lighter: route groups (MapGroup), endpoint filters, TypedResults for accurate OpenAPI metadata, and support for native AOT, which MVC controllers do not have.

Route constraints select, they do not validate

A constraint such as {id:int} is part of matching. If the segment is not an integer, the route does not match at all, and with no other candidate the request ends at the 404 terminal. Without the constraint, the route matches and binding "abc" to an int parameter fails with a 400. Use constraints to tell routes apart, and validation to reject bad input. The model below is a tiny matcher that only knows literals, {name} and {name:int}.

1public static class Solution2{3    static string Match(string template, string path)4    {5        var t = template.Trim('/').Split('/');6        var p = path.Trim('/').Split('/');7        if (t.Length != p.Length) return path + " -> no match";8 9        var values = new List<string>();10        for (int i = 0; i < t.Length; i++)11        {12            if (t[i].StartsWith("{"))13            {14                var inner = t[i].Trim('{', '}').Split(':');15                if (inner.Length == 2 && inner[1] == "int" && !int.TryParse(p[i], out _))16                    return path + " -> no match";17                values.Add(inner[0] + "=" + p[i]);18            }19            else if (!string.Equals(t[i], p[i], StringComparison.OrdinalIgnoreCase))20                return path + " -> no match";21        }22        return path + " -> " + string.Join(", ", values);23    }24 25    public static List<string> Run() => new()26    {27        Match("/orders/{id:int}", "/orders/42"),28        Match("/orders/{id:int}", "/orders/abc"),29        Match("/orders/{id}", "/orders/abc"),30        Match("/orders/{id:int}", "/orders/42/lines"),31    };32}

Where a parameter's value comes from

An attribute ([FromRoute], [FromQuery], [FromBody], [FromHeader], [FromServices], [FromForm]) always decides. Without one, a minimal API handler infers the source roughly like this:

1. Well-known types: HttpContext, HttpRequest, HttpResponse, CancellationToken, ClaimsPrincipal.
2. Simple types (int, string, Guid, DateTime and anything with a TryParse): from the route if the template has a parameter of that name, otherwise from the query string.
3. A type registered in the container: from services.
4. Anything else: deserialised from the JSON body. Only one parameter may come from the body.

The list leaves out rarer cases, such as a type that binds itself with a static BindAsync method. In a minimal API, a parameter that is not nullable and has no default value is required: when the request does not supply it, the endpoint answers 400 without running the handler. int?, or a default value make it optional. A value that does not parse, such as for an or an , is a 400 either way. The model below applies the four rules to a POST handler's parameters.

1public static class Solution2{3    static readonly HashSet<string> Special = new() { "HttpContext", "CancellationToken", "ClaimsPrincipal" };4    static readonly HashSet<string> Simple = new() { "int", "string", "Guid", "DateTime" };5 6    static string Source(string name, string type, HashSet<string> routeParams, HashSet<string> services)7    {8        if (Special.Contains(type)) return "special";9        if (Simple.Contains(type)) return routeParams.Contains(name) ? "route" : "query";10        if (services.Contains(type)) return "services";11        return "body";12    }13 14    public static List<string> Run()15    {16        // app.MapPost("/shops/{shopId}/orders",17        //     (int shopId, string? coupon, CreateOrder body, ShopDb db, CancellationToken ct) => ...)18        var route = new HashSet<string> { "shopId" };19        var services = new HashSet<string> { "ShopDb" };20        var parameters = new[]21        {22            ("shopId", "int"), ("coupon", "string"), ("body", "CreateOrder"),23            ("db", "ShopDb"), ("ct", "CancellationToken"),24        };25        return parameters.Select(p => p.Item1 + ": " + Source(p.Item1, p.Item2, route, services)).ToList();26    }27}

Common mistakes

• Using a route constraint as input validation. /orders/abc against {id:int} is a 404, which tells the client the resource does not exist rather than that the request was malformed.
• Checking whether a name appears anywhere in the template. orders in /orders/{id} is a literal segment, not a route parameter, so a parameter called orders binds from the query.
• Two complex parameters on one handler. Both infer the body, and the framework rejects the endpoint with an InvalidOperationException instead of guessing. Merge them into one request type.
• Expecting automatic 400s for invalid models in minimal APIs on .NET 9. That behaviour comes from [ApiController]; minimal APIs on .NET 9 need an endpoint filter or explicit validation.

What interviewers ask

• Controllers or minimal APIs for a new service, and why? Either is a defensible answer; name concrete trade-offs: filters and conventions versus less ceremony, AOT and route groups.
• A client calls /orders/abc and gets 404. Why not 400? The int constraint is part of route matching, so no endpoint matched.
• How does ASP.NET Core decide where a parameter comes from? Attributes first; otherwise special types, route or query for simple types, services, and the body for complex types.