Minimal APIs in ASP.NET Core 9

The journey of Minimal APIs in ASP.NET Core has been remarkable, and with version 9, we see a significant evolution that makes web development more intuitive and powerful than ever before. Let's explore how these improvements transform the way we build web applications.

Understanding the Evolution

When Minimal APIs were first introduced, they aimed to simplify web development by reducing boilerplate code. In ASP.NET Core 9, this vision has matured into a robust framework that maintains simplicity while offering powerful features. Let's walk through the improvements and understand how they benefit your development process.

The Foundation: Basic Endpoint Creation

Let's start with a simple example to see how endpoint creation has evolved:

// Previous approach in .NET 8
var app = WebApplication.Create(args);
app.MapGet("/hello", () => "Hello, World!");

// Enhanced approach in .NET 9
var app = WebApplication.Create(args);
app.MapGet("/hello", () => TypedResults.Ok("Hello, World!"))
   .WithName("GetHello")
   .WithOpenApi()
   .RequireAuthorization();        

In this example, we can see how .NET 9 brings more fluent and expressive endpoint definitions. The new TypedResults provides better type safety and clearer intent in your API responses.

Understanding Route Groups

ASP.NET Core 9 introduces enhanced route groups that make API organization more intuitive:

var builder = WebApplication.Create(args);
var app = builder.Build();

// Creating a route group for product-related endpoints
var products = app.MapGroup("/products")
    .WithTags("Products")    // OpenAPI tagging
    .RequireAuthorization() // Apply authorization to all endpoints
    .WithOpenApi();        // Enable OpenAPI documentation

// Define endpoints within the group
products.MapGet("/", async (IProductRepository repo) => 
    await repo.GetAllProducts())
    .WithName("GetProducts")
    .WithSummary("Retrieves all products")
    .WithDescription("Returns a list of all available products in the catalog.");

products.MapGet("/{id}", async (int id, IProductRepository repo) =>
    await repo.GetProductById(id) is Product product
        ? TypedResults.Ok(product)
        : TypedResults.NotFound());

products.MapPost("/", async (Product product, IProductRepository repo) =>
{
    await repo.AddProduct(product);
    return TypedResults.Created($"/products/{product.Id}", product);
});        

This organization makes your API structure more maintainable and easier to understand. The group-level configurations reduce code duplication and enforce consistent behavior across related endpoints.

Enhanced Parameter Binding

ASP.NET Core 9 introduces more sophisticated parameter binding capabilities:

public class SearchParameters
{
    public string? Query { get; set; }
    public int Page { get; set; } = 1;
    public int PageSize { get; set; } = 10;
    public string? SortBy { get; set; }
}

app.MapGet("/search", async (
    [AsParameters] SearchParameters parameters,
    ISearchService searchService) =>
{
    var results = await searchService.Search(
        parameters.Query,
        parameters.Page,
        parameters.PageSize,
        parameters.SortBy
    );
    
    return TypedResults.Ok(new
    {
        Items = results,
        Page = parameters.Page,
        PageSize = parameters.PageSize,
        Query = parameters.Query
    });
});        

The [AsParameters] attribute provides a clean way to handle complex query parameters, making your endpoints more organized and maintainable.

Type-Safe Results

The new TypedResults improvements in .NET 9 bring better type safety and clearer intent to your API responses:

app.MapGet("/orders/{id}", async (int id, IOrderService orderService) =>
{
    var result = await orderService.GetOrderById(id);
    
    // Enhanced pattern matching with TypedResults
    return result switch
    {
        Order order => TypedResults.Ok(order),
        null => TypedResults.NotFound("Order not found"),
        _ => TypedResults.Problem("An unexpected error occurred")
    };
});        

This approach provides better compile-time safety and makes your API responses more predictable and easier to document.

Real-World Application Example

Let's look at a more comprehensive example that brings together various improvements:

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        
        // Adding services
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen();
        builder.Services.AddAuthorization();
        
        var app = builder.Build();
        
        // API versioning group
        var v1 = app.MapGroup("/api/v1")
            .WithOpenApi()
            .WithTags("v1");
            
        // Orders management
        var orders = v1.MapGroup("/orders")
            .RequireAuthorization()
            .WithTags("Orders");
            
        orders.MapGet("/", async (
            [AsParameters] PaginationParameters pagination,
            IOrderService orderService) =>
        {
            var orders = await orderService.GetOrders(
                pagination.Page,
                pagination.PageSize
            );
            
            return TypedResults.Ok(new
            {
                Items = orders,
                Pagination = pagination
            });
        })
        .WithName("GetOrders")
        .WithSummary("Retrieves all orders")
        .ProducesValidationProblem();
        
        orders.MapGet("/{id}", async (
            int id,
            IOrderService orderService) =>
        {
            var order = await orderService.GetOrderById(id);
            
            return order is null
                ? TypedResults.NotFound()
                : TypedResults.Ok(order);
        })
        .WithName("GetOrderById");
        
        orders.MapPost("/", async (
            Order order,
            IOrderService orderService,
            IValidator<Order> validator) =>
        {
            var validation = await validator.ValidateAsync(order);
            
            if (!validation.IsValid)
            {
                return TypedResults.ValidationProblem(
                    validation.ToDictionary()
                );
            }
            
            var result = await orderService.CreateOrder(order);
            
            return TypedResults.Created(
                $"/api/v1/orders/{result.Id}",
                result
            );
        })
        .WithName("CreateOrder");
        
        app.Run();
    }
}        

This example demonstrates how the new features work together to create a clean, maintainable, and type-safe API structure.

Best Practices and Recommendations

When working with Minimal APIs in ASP.NET Core 9, consider these practices:

1. Use route groups to organize related endpoints and apply common configurations.
2. Leverage TypedResults for consistent and type-safe API responses.
3. Implement parameter binding with [AsParameters] for complex query parameters.
4. Take advantage of the enhanced OpenAPI support for better API documentation.
5. Use the new validation features to ensure data integrity.

Performance Considerations

ASP.NET Core 9's Minimal APIs bring performance improvements through:

1. Optimized route handling
2. More efficient parameter binding
3. Reduced memory allocations in common scenarios
4. Better integration with native AOT compilation

Migration Strategy

When upgrading from previous versions:

1. Review existing endpoints and consider organizing them into route groups
2. Replace raw result types with TypedResults
3. Update parameter binding to use the new [AsParameters] attribute where appropriate
4. Take advantage of the enhanced OpenAPI integration

Conclusion

The improvements to Minimal APIs in ASP.NET Core 9 represent a significant step forward in web development. By combining simplicity with powerful features, they provide developers with the tools needed to build modern, maintainable, and performant web APIs. Whether you're building a small service or a large-scale application, these enhancements help you write better code more efficiently.