ASP.NET Minimal API - Quick Reference
Deep Knowledge: Use mcp__documentation__fetch_docs with technology: aspnet-core, topic: minimal-api for comprehensive documentation.
Basic Endpoints
var app = WebApplication.Create(args);
app.MapGet("/api/users", async (IUserService service) =>
Results.Ok(await service.GetAllAsync()));
app.MapGet("/api/users/{id:int}", async (int id, IUserService service) =>
await service.GetByIdAsync(id) is { } user
? Results.Ok(user)
: Results.NotFound());
app.MapPost("/api/users", async (CreateUserRequest request, IUserService service) =>
{
var user = await service.CreateAsync(request);
return Results.Created($"/api/users/{user.Id}", user);
});
app.MapPut("/api/users/{id:int}", async (int id, UpdateUserRequest request, IUserService service) =>
await service.UpdateAsync(id, request) ? Results.NoContent() : Results.NotFound());
app.MapDelete("/api/users/{id:int}", async (int id, IUserService service) =>
{
await service.DeleteAsync(id);
return Results.NoContent();
});
app.Run();
Route Groups
var users = app.MapGroup("/api/users")
.WithTags("Users")
.RequireAuthorization();
users.MapGet("/", GetAll);
users.MapGet("/{id:int}", GetById);
users.MapPost("/", Create);
// Nested groups
var admin = app.MapGroup("/api/admin")
.RequireAuthorization("AdminOnly");
admin.MapGroup("/users").MapGet("/", GetAllUsers);
Endpoint Filters
// Validation filter
public class ValidationFilter<T> : IEndpointFilter where T : class
{
public async ValueTask<object?> InvokeAsync(
EndpointFilterInvocationContext context,
EndpointFilterDelegate next)
{
var argument = context.Arguments.OfType<T>().FirstOrDefault();
if (argument is null)
return Results.BadRequest("Invalid request body");
var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
if (validator is not null)
{
var result = await validator.ValidateAsync(argument);
if (!result.IsValid)
return Results.ValidationProblem(result.ToDictionary());
}
return await next(context);
}
}
// Apply filter
users.MapPost("/", Create).AddEndpointFilter<ValidationFilter<CreateUserRequest>>();
TypedResults (.NET 7+)
app.MapGet("/api/users/{id:int}", async Task<Results<Ok<UserResponse>, NotFound>> (int id, IUserService service) =>
await service.GetByIdAsync(id) is { } user
? TypedResults.Ok(user)
: TypedResults.NotFound());
Anti-Patterns
| Anti-Pattern | Why It's Bad | Correct Approach |
|---|
| All endpoints in Program.cs | Hard to maintain | Use route groups and extension methods |
| No validation | Accepts bad input | Use endpoint filters |
| Inline business logic | Not testable | Inject services |
| Not using TypedResults | No OpenAPI metadata | Use TypedResults for typed responses |
Quick Troubleshooting
| Issue | Likely Cause | Solution |
|---|
| Parameter not bound | Wrong type or name | Use explicit [FromRoute] / [FromQuery] |
| Filter not executing | Not registered | Add with AddEndpointFilter<T>() |
| OpenAPI missing types | Using Results.Ok() | Use TypedResults.Ok() |
| Route conflicts | Ambiguous routes | Add route constraints like {id:int} |
