C# Reference ยท .NET, Tools and Concepts
Minimal APIs
Reference for ASP.NET Core minimal APIs: MapGet and friends, parameter binding, TypedResults, route groups, filters and status codes, with live demos.
Minimal APIs map an HTTP method and a URL pattern directly to a delegate. There are no controller classes: app.MapGet("/path", handler) is the whole endpoint. They run on the same routing, binding, authentication and JSON machinery as MVC controllers, and they are the recommended starting point for new HTTP APIs in .NET.
Parameters of the handler are filled in automatically from the route, query string, headers, body or the dependency injection container. The return value becomes the response: strings are written as text, objects as JSON, and IResult values (such as TypedResults.NotFound()) control the status code.
app.MapGet("/users/{id:int}", (int id) => $"user {id}");
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Route groups share a prefix and configuration. Endpoint filters wrap a handler, like small middleware for one endpoint or group.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
IEndpointConventionBuilder MapGet(this IEndpointRouteBuilder endpoints, string pattern, Delegate handler); // MapPost, MapPut, MapDelete, MapPatch have the same shape RouteHandlerBuilder MapMethods(this IEndpointRouteBuilder endpoints, string pattern, IEnumerable<string> httpMethods, Delegate handler); RouteGroupBuilder MapGroup(this IEndpointRouteBuilder endpoints, string prefix);
| Name | Description |
|---|---|
pattern |
The route template, such as /items/{id:int}. Constraints (:int, :guid, :min(1)) reject non-matching values with a 404. |
handler |
A lambda, local function or method group. Its parameters are bound automatically. |
prefix |
Shared route prefix for a group. |
Where a parameter comes from (in this order of inference):
| Source | Rule |
|---|---|
| Route | Name matches a in the pattern. |
| Query string | Simple types (string, int, enums...) that are not in the route. Nullable or default values make them optional. |
| Body (JSON) | One complex type that is not a registered service. Add [FromBody] to be explicit. |
| Services | A type registered in DI, or marked [FromServices]. |
| Header, form | Use [FromHeader], [FromForm]. |
| Special | HttpContext, HttpRequest, HttpResponse, CancellationToken, ClaimsPrincipal. |
Return values:
| Handler returns | Response |
|---|---|
string |
200 with text/plain. |
| Object, record, collection | 200 with JSON. |
IResult (Results.*, TypedResults.*) |
Whatever the result says. |
void, Task |
200 with an empty body. |
Errors: a body that is not valid JSON, or a required parameter that is missing or cannot be converted, gives 400 Bad Request without calling your handler.
Usage notes
TypedResultsoverResults.TypedResults.Ok(value)carries its type, so OpenAPI metadata is accurate and tests can assert on the result type. Declare several outcomes with a union return type, such asResults<Ok<Item>, NotFound>.- A non-nullable reference parameter is required.
string namerejects requests without it;string? namemakes it optional. Nullable annotations affect behavior here. - Local variables captured by a lambda are shared by all requests. The in-memory dictionaries in these demos are not thread safe; use real storage or
ConcurrentDictionaryin an app. - Group configuration applies to every endpoint inside:
RequireAuthorization(),WithTags(...),AddEndpointFilter(...),RequireRateLimiting(...). - Organize growing APIs with extension methods (
app.MapItemEndpoints()) or static classes with handler methods, soProgram.csstays short. - Validation is not automatic for minimal APIs; check input in the handler, a filter, or a validation library.
- JSON uses
System.Text.Jsonwith web defaults (camelCase names, case-insensitive reading). Change it withbuilder.Services.ConfigureHttpJsonOptions. - Performance: handlers are compiled into request delegates once at startup, so the per-request overhead is small. Prefer
asynchandlers for I/O.