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}