d-subrahmanyam/aspnet-minimal-api

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} |