Skip to content
Tutorials Center
My learning

Topics

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.

C#
app.MapGet("/users/{id:int}", (int id) => $"user {id}");

Try it

C# Binding and results

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.

C# Groups and endpoint filters

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

C#
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

  • TypedResults over Results. 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 as Results<Ok<Item>, NotFound>.
  • A non-nullable reference parameter is required. string name rejects requests without it; string? name makes 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 ConcurrentDictionary in 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, so Program.cs stays short.
  • Validation is not automatic for minimal APIs; check input in the handler, a filter, or a validation library.
  • JSON uses System.Text.Json with web defaults (camelCase names, case-insensitive reading). Change it with builder.Services.ConfigureHttpJsonOptions.
  • Performance: handlers are compiled into request delegates once at startup, so the per-request overhead is small. Prefer async handlers for I/O.