Route Groups and Endpoint Filters

The repetition problem

Without grouping, every endpoint repeats its prefix and its metadata:

app.MapGet("/api/v1/books", GetAll).WithTags("Books").RequireAuthorization();
app.MapGet("/api/v1/books/{id:int}", GetById).WithTags("Books").RequireAuthorization();
app.MapPost("/api/v1/books", Create).WithTags("Books").RequireAuthorization();
app.MapDelete("/api/v1/books/{id:int}", Delete).WithTags("Books").RequireAuthorization();

Four endpoints, four copies of the same three things. Change the version prefix and you edit every line.

MapGroup

MapGroup creates a group. Everything set on the group applies to every endpoint inside it:

var books = app.MapGroup("/api/v1/books")
               .WithTags("Books")
               .RequireAuthorization();

books.MapGet("/", GetAll);
books.MapGet("/{id:int}", GetById);
books.MapPost("/", Create);
books.MapDelete("/{id:int}", Delete);

Same four endpoints, and now the prefix, the tag and the auth requirement live in one place.

The route inside the group is the part after the prefix. "/" means the group root, so books.MapGet("/", ...) handles GET /api/v1/books.

Nesting groups

Groups nest, and the prefixes join:

var api = app.MapGroup("/api").WithTags("API");
var v1 = api.MapGroup("/v1");
var books = v1.MapGroup("/books");

books.MapGet("/{id:int}", GetById);        // GET /api/v1/books/{id}

var reviews = books.MapGroup("/{bookId:int}/reviews");
reviews.MapGet("/", GetReviews);           // GET /api/v1/books/{bookId}/reviews
reviews.MapPost("/", AddReview);           // POST /api/v1/books/{bookId}/reviews

Route parameters from a parent group are available to the handlers inside. GetReviews(int bookId) binds from the group’s own template.

This makes versioning almost free:

app.MapGroup("/api/v1").MapBookEndpointsV1();
app.MapGroup("/api/v2").MapBookEndpointsV2();

Mixing public and protected endpoints

A common shape is a public group and a protected group under the same prefix:

var books = app.MapGroup("/api/books").WithTags("Books");

// Anyone can read
books.MapGet("/", GetAll);
books.MapGet("/{id:int}", GetById);

// Writing needs a token
var admin = books.MapGroup("").RequireAuthorization("AdminOnly");
admin.MapPost("/", Create);
admin.MapPut("/{id:int}", Update);
admin.MapDelete("/{id:int}", Delete);

An empty prefix adds no path segment, so the sub group exists purely to carry the policy.

What an endpoint filter is

A filter runs around a handler. It sees the arguments before the handler runs, and the result after. It is the minimal API answer to action filters in MVC.

app.MapGet("/api/books", GetAll)
   .AddEndpointFilter(async (context, next) =>
   {
       Console.WriteLine("before the handler");
       object? result = await next(context);
       Console.WriteLine("after the handler");
       return result;
   });

next(context) calls the next filter, or the handler itself if this is the last one. Whatever you return becomes the response, so a filter can replace the result entirely.

Short circuiting

Return a result without calling next and the handler never runs. That is how validation filters work:

.AddEndpointFilter(async (context, next) =>
{
    var request = context.GetArgument<CreateBookRequest>(0);

    if (string.IsNullOrWhiteSpace(request.Title))
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            ["title"] = new[] { "Title is required." }
        });

    return await next(context);
});

context.GetArgument<T>(index) reads a handler parameter by position. The index is zero based and counts every parameter, including injected services, so it is brittle. A safer alternative when the type is unique:

var request = context.Arguments.OfType<CreateBookRequest>().FirstOrDefault();

A reusable validation filter

Writing the same check for every request type is the thing we are trying to avoid. Make it generic:

using System.ComponentModel.DataAnnotations;

public class ValidationFilter<T> : IEndpointFilter where T : class
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        T? model = context.Arguments.OfType<T>().FirstOrDefault();

        if (model is null)
            return Results.BadRequest("Request body is missing.");

        var results = new List<ValidationResult>();
        bool valid = Validator.TryValidateObject(
            model, new ValidationContext(model), results, validateAllProperties: true);

        if (!valid)
        {
            var errors = results
                .SelectMany(r => r.MemberNames.Select(m => (Member: m, r.ErrorMessage)))
                .GroupBy(x => x.Member)
                .ToDictionary(g => g.Key, g => g.Select(x => x.ErrorMessage ?? "").ToArray());

            return Results.ValidationProblem(errors);
        }

        return await next(context);
    }
}

Now any endpoint can opt in with one line, and your [Required] and [Range] attributes finally do something in a minimal API:

books.MapPost("/", Create).AddEndpointFilter<ValidationFilter<CreateBookRequest>>();

Filters on a whole group

Add a filter to the group and every endpoint in it gets it:

var books = app.MapGroup("/api/books")
    .AddEndpointFilter(async (context, next) =>
    {
        var watch = System.Diagnostics.Stopwatch.StartNew();
        object? result = await next(context);
        watch.Stop();

        context.HttpContext.Response.Headers["X-Elapsed-Ms"] =
            watch.ElapsedMilliseconds.ToString();

        return result;
    });

Every endpoint under /api/books now reports its own timing.

Order of execution

Filters run in the order you add them, wrapping each other like layers of an onion:

app.MapGet("/test", handler)
   .AddEndpointFilter(A)
   .AddEndpointFilter(B);

A before
  B before
    handler
  B after
A after

Group filters are added before endpoint filters, so a group filter is the outermost layer.

Filters versus middleware

They look similar and solve different problems.

Middleware runs for every request that reaches the pipeline, before routing has necessarily finished. It works with the raw HttpContext. Use it for things that apply to the whole application: HTTPS redirection, CORS, authentication, global error handling.

Filters run after routing and after model binding, so they see the typed arguments and can change the result. Use them for things that apply to specific endpoints: validating a request object, checking that a resource belongs to the caller, adding a per endpoint header.

If your logic needs the bound model, it has to be a filter. Middleware runs too early to see it.

Quick recap

• MapGroup shares a route prefix and metadata across many endpoints.
• Groups nest, and their prefixes and route parameters combine.
• A sub group with an empty prefix is a neat way to apply a policy to a subset of endpoints.
• An endpoint filter wraps the handler. Call next(context) to continue, or return early to short circuit.
• context.Arguments.OfType<T>() is safer than GetArgument<T>(index), because it does not depend on parameter order.
• A generic ValidationFilter<T> restores automatic data annotation validation, which minimal APIs otherwise lack.
• Filters run in the order added, outermost first, and group filters wrap endpoint filters.
• Middleware is for the whole app and the raw context. Filters are for specific endpoints and typed arguments.