Structuring and grouping dotnet minimal API endpoints

Minimal APIs since .NET 6 are a great way to create web APIs with minimal code. But, as your API grows, you need to structure and group your endpoints. In this blog post, I will show you how to structure and group your minimal API endpoints.

1. Using Program.cs for mapping endpoints

It is quite often that you see tutorials for minimal APIs using the Program.cs to map all endpoints. It looks like this:

var builder = WebApplication.CreateBuilder(args);

builder.Services
       .AddEndpointsApiExplorer()
       .AddSwaggerGen();
       
var app = builder.Build();

app.UseHttpsRedirection();

app.MapGet("", () => CallSomeMethod());

app.MapGet("/{id}", (int id) => SomeMethod(id));

But, with this approach your Program.cs file can get quite large and hard to maintain. So as your API grows, you need to structure and group your endpoints.

2. Structuring and grouping endpoints

To structure and group your minimal API endpoints, we will introduce a new interface called ‘IEndpoint’. This interface will have a method ‘MapEndpoints’ that will be used to map the endpoints.

public interface IEndpoint
{
    static abstract void MapEndpoint(IEndpointRouteBuilder app);
}

Now, we can create a new class for each endpoint or a group of endpoints. This way, we can group related endpoints together.

public class UserEndpoint : IEndpoint
{
    public static void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapGet("/users", () => CallSomeMethod());
        app.MapGet("/users/{id}", (int id) => SomeMethod(id));
    }
}

To wire up the endpoints, we can use reflection or in our case we can implement an extension method for IEndpointRouteBuilder. Like this:

public static class EndpointsExtensions
{
    public static IEndpointRouteBuilder AddEndpoint<TEndpoint>(this IEndpointRouteBuilder app) where TEndpoint : IEndpoint
    {
        TEndpoint.MapEndpoint(app);
        return app;
    }
}

Wire up the endpoints in the Program.cs file like this:

//... 

var builder = WebApplication.CreateBuilder(args);

builder.Services
       .AddEndpointsApiExplorer()
       .AddSwaggerGen();
       
var app = builder.Build();

app.MapGroup("/user")
  .AddEndpoint<UserEndpoint>();

3. Conclusion

With the showed approach, you can structure and group your minimal API endpoints in a more maintainable way. This way, you can keep your Program.cs file clean and easy to read. It is possible to maintain a large API with many endpoints without losing the overview. This way you can create one file per endpoint or group endpoints together that belong together in one file.