Minimal APIs and Routing

Overview

Minimal APIs are a streamlined way of building HTTP APIs in ASP.NET Core using a top-level, functional style with minimal ceremony — no controllers, startup classes, or attribute routing required.

They are ideal for:

• Lightweight services
• Microservices
• Serverless functions
• Rapid prototyping

"Minimal APIs reduce boilerplate by letting you define routes and handlers directly in Program.cs, while still leveraging the full ASP.NET Core pipeline, middleware, and DI."

Routing in Minimal APIs

Routing is code-based rather than attribute-based. You define endpoints using HTTP method extension methods like .MapGet, .MapPost, etc.

Routing supports:

• Route templates (e.g., /products/{id:int})
• Parameter binding from query, route, headers, body, services
• Route constraints and filters

Example: Minimal API with Routing and DI

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IProductService, ProductService>();

var app = builder.Build();

// Basic GET route with inline handler
app.MapGet("/", () => "Hello, World!");

// Route with parameter and DI
app.MapGet("/products/{id:int}", (int id, IProductService service) =>
{
    var product = service.GetProductById(id);
    return product is not null ? Results.Ok(product) : Results.NotFound();
});

app.Run();

Service & Model Example

public interface IProductService
{
    Product? GetProductById(int id);
}

public class ProductService : IProductService
{
    private static readonly List<Product> _products = new()
    {
        new Product { Id = 1, Name = "Coffee" },
        new Product { Id = 2, Name = "Tea" }
    };

    public Product? GetProductById(int id) =>
        _products.FirstOrDefault(p => p.Id == id);
}

public record Product(int Id, string Name);

Benefits of Minimal APIs

Benefit	Details
Fast to develop	Minimal code needed — great for PoCs and microservices
DI support	Constructor-less DI via parameter injection
Testable	Handlers are just methods/functions — easily unit testable
Performance	Slightly faster cold start than full MVC
Full ASP.NET features	Can add middleware, filters, logging, Swagger, etc.

Downsides / Limitations

Limitation	Explanation
Lacks structure	Harder to manage in large projects
No controllers	No attribute routing or action filters
Less discoverable	Can grow messy without grouping
Harder to apply layered architecture (MVC)	Custom organization is needed

When to Use Minimal APIs (vs MVC)

Use Case	Use Minimal API?	Reason
Microservice	✅ Yes	Small surface, fast routing
Proof of Concept	✅ Yes	Rapid iteration
Monolith / UI app	❌ Prefer MVC	Cleaner separation of concerns
Public HTTP API	✅/❌ Mixed	Use Minimal APIs for small APIs; MVC for complex validation & filters
REST + Swagger	✅ Yes	Minimal APIs support OpenAPI/Swagger with annotations

Routing Features in Detail

Route Templates

app.MapGet("/users/{userId:int}", (int userId) => { /*...*/ });

Route Constraints

• {id:int} – integer
• {slug:alpha} – alphabet only
• {*path} – wildcard
• Optional params: /users/{id?}

Route Filters (Preview/.NET 8+)

app.MapGet("/admin", () => "Admin")
   .AddEndpointFilter(async (ctx, next) =>
   {
       // Perform auth/validation
       return await next(ctx);
   });

Summary

"Minimal APIs in .NET provide a low-friction way to build HTTP endpoints using top-level route mapping, great for microservices or lean web APIs.

Minimal APIs support DI, routing, filters, and middleware while avoiding the overhead of controllers.

They are used when speed and simplicity matter — like in edge services or internal tooling — but switch to MVC for more structured, scalable apps.