Mapping a group of endpoints to a resource url

[mrhighstone]

Consider two group of API endpoints, TodoLists and TodoItems.

How could I organise the endpoint mapping so that todo-items are grouped as resources under their respective todo-lists?
So instead of fetching todo-item 456 here /api/todoitems/456
I want to group todo-item 456 under the todo-list 123 like so /api/todolists/123/todoitems/456

I would prefer to leverage the existing EndpointGroupBase and IEndpointRouteBuilderExtensions for this. Would this somehow be supported?

[mrhighstone]

I decided to opt-out of the existing EndpointGroupBase and IEndpointRouteBuilderExtensions and use a more generic approach as described by Renato Golia in How to automatically register Minimal API endpoints in ASP.NET Core

This introduces a new dependency but I believe this comes with a more simple implementation, adheres to the default behaviour of the existing IEndpointRouteBuilder and TBuilder extensions and therefore makes it straightforward to implement custom or default behaviour.

The magic and heavylifting is implemented in the IEndpointRouteBuilderGeneration class:

public static partial class IEndpointRouteBuilderGeneration
{
    [GenerateServiceRegistrations(
        AssignableTo = typeof(IEndpointGroup),
        CustomHandler = nameof(MapEndpointsInternal))]
    public static partial IEndpointRouteBuilder MapEndpoints(this IEndpointRouteBuilder builder);

    private static void MapEndpointsInternal<T>(IEndpointRouteBuilder builder) where T : IEndpointGroup, new()
    {
        var instance = new T();
        instance.MapEndpoints(builder);
    }
}

The GenerateServiceRegistrations attribute comes from the ServiceScan.SourceGenerator package and requires this NuGet Package be installed and the following using statement declared:

using ServiceScan.SourceGenerator;

The IEndpointGroup acts as a marker interface for the class that implement the method delegates:

public interface IEndpointGroup
{
    void MapEndpoints(IEndpointRouteBuilder builder);
}

Then in program.cs the endpoints are mapped:

app.MapEndpoints();

I have added some additional extension methods to infer the group and method names, to avoid having to explicitly decorate my method delegates with attributes but this is syntactic sugar:

public static class IEndpointRouteBuilderExtensions
{
    // Generic extensions for mapping groups and endpoints with defaults based on the group
    public static IEndpointRouteBuilder MapGroupWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, IEndpointGroup group)
    {
        return builder.MapGroup(pattern)
            .WithDefaults(group);
    }

    public static TBuilder WithDefaults<TBuilder>(this TBuilder builder, IEndpointGroup group) where TBuilder : IEndpointConventionBuilder
    {
        return builder
            .WithTags(group.GetType().Name);
    }

    // Generic extensions for mapping groups and endpoints with defaults based on the handler
    public static IEndpointConventionBuilder MapGetWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, Delegate handler)
    {
        return builder.MapGet(pattern, handler).WithName(handler.Method.Name)
            .WithDefaults(handler);
    }

    public static IEndpointConventionBuilder MapPostWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, Delegate handler)
    {
        return builder.MapPost(pattern, handler)
            .WithDefaults(handler);
    }

    public static IEndpointConventionBuilder MapPutWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, Delegate handler)
    {
        return builder.MapPut(pattern, handler)
            .WithDefaults(handler);
    }

    public static IEndpointConventionBuilder MapPatchWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, Delegate handler)
    {
        return builder.MapPatch(pattern, handler)
            .WithDefaults(handler);
    }

    public static IEndpointConventionBuilder MapDeleteWithDefaults(this IEndpointRouteBuilder builder, [StringSyntax("Route")] string pattern, Delegate handler)
    {
        return builder.MapDelete(pattern, handler)
            .WithDefaults(handler);
    }

    public static TBuilder WithDefaults<TBuilder>(this TBuilder builder, Delegate handler) where TBuilder : IEndpointConventionBuilder
    {
        return builder
            .WithName(handler.Method.Name)
            .WithSummary(handler.Method.Name);        
    }    
}

A sample implementation of the group of endpoints, implementing IEndpointGroup

public class Accounts : IEndpointGroup
{
    public void MapEndpoints(IEndpointRouteBuilder builder)
    {
        var group = builder
            .MapGroupWithDefaults("ledgers/{ledgerId}/accounts", this);

        //group.RequireAuthorization();

        group.MapGetWithDefaults("", GetAccountsWithPagination);
        group.MapGetWithDefaults("{id}", GetAccount);
        group.MapPostWithDefaults("", CreateAccount);
        group.MapPutWithDefaults("{id}", UpdateAccount);
        group.MapDeleteWithDefaults("{id}", DeleteAccount);
    }

    public async Task<Ok<PaginatedList<AccountInfo>>> GetAccountsWithPagination(ISender sender, [AsParameters] GetAccountsWithPaginationQuery query)
    {
        var result = await sender.Send(query);

        return TypedResults.Ok(result);
    }
    
    //etc ...
}

And that's it! 😃

When implementing this pattern, the classes EndpointGroupBase, EndpointGroup and WebApplicationExtensions can be deleted.

[jasontaylordev]

@mrhighstone, thanks for raising this.

On nested resource paths

The template convention maps each IEndpointGroup to a flat /api/{ClassName} prefix by default. As of Release v10.6.0, groups can override that convention by declaring a RoutePrefix property:

public class TodoItems : IEndpointGroup
{
    public static string RoutePrefix => "/api/TodoLists/{todoListId}/TodoItems";

    public static void Map(RouteGroupBuilder groupBuilder)
    {
        groupBuilder.MapPatch(UpdateTodoItemDetail, "UpdateDetail/{id}").RequireAuthorization();
        // ...
    }

    public static async Task<Results<NoContent, BadRequest>> UpdateTodoItemDetail(
        ISender sender, int todoListId, int id, UpdateTodoItemDetailCommand command)
    {
        // ...
    }
}

The todoListId parameter binds directly from the route segment. Groups that don't declare RoutePrefix continue to use /api/{ClassName} automatically - no change required for the common case.

On your alternative approach

Your approach is solid, and the static abstract interface you proposed aligns closely with what landed in the release. I considered using ServiceScan.SourceGenerator for endpoint discovery but opted for reflection instead - the generator requires [GenerateServiceRegistrations] to be declared in the consuming assembly, and I'm planning to extract this functionality into a separate package at some point. Reflection at startup carries negligible cost and keeps that option open. Note also that the template has moved IEndpointGroup to a static abstract interface, removing the need to instantiate endpoint classes - your instance-based new T() approach is the older style.

[mrhighstone]

Ahoy! Thanks for getting back on this. Seems that we simultaneously resolved this 😉

I agree for the additional dependency and understand your view on this. Additional benefit is compile-time validation.

I intentionally applied the instance based approach instead of static abstract, to be compatible with the existing implementation 🤭