All Articles
.NETC#REST API

Getting Started with .NET Minimal APIs

A practical introduction to building lightweight HTTP APIs with .NET Minimal APIs — less boilerplate, same power.

2026-05-20·6 min read

.NET Minimal APIs were introduced in .NET 6 and have been refined with every release since. They strip away the ceremony of the traditional controller-based approach and let you define HTTP endpoints directly in Program.cs with a few lines of code.

Why Minimal APIs?

Traditional ASP.NET Core projects require controllers, action methods, routing attributes, and a fair amount of boilerplate. For microservices or smaller APIs, that overhead adds up.

Minimal APIs reduce the surface area:

  • No controller classes needed
  • Built-in route grouping with MapGroup
  • Native support for IResult return types
  • First-class OpenAPI/Swagger integration

A Minimal Example

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/products", async (AppDbContext db) =>
    await db.Products.ToListAsync());

app.MapPost("/products", async (Product product, AppDbContext db) =>
{
    db.Products.Add(product);
    await db.SaveChangesAsync();
    return Results.Created($"/products/{product.Id}", product);
});

app.Run();

The AppDbContext is injected directly from the DI container — no constructor injection on a controller class required.

Route Groups

When your API grows, MapGroup keeps things organised without controllers:

var products = app.MapGroup("/products").RequireAuthorization();

products.MapGet("/", GetAllProducts);
products.MapGet("/{id}", GetProduct);
products.MapPost("/", CreateProduct);
products.MapPut("/{id}", UpdateProduct);
products.MapDelete("/{id}", DeleteProduct);

Each handler can be a static method, a local function, or a lambda. Moving handlers to static methods keeps Program.cs clean while retaining the minimal structure.

Filters

Minimal APIs support endpoint filters, which work like middleware scoped to specific routes:

app.MapPost("/products", CreateProduct)
   .AddEndpointFilter<ValidationFilter<Product>>();

This is useful for request validation, logging, or short-circuiting with a 400 Bad Request before the handler runs.

When to Use Minimal APIs

Minimal APIs are a great fit when you want:

  • A focused microservice with a small surface area
  • Fast iteration on a prototype
  • A clean starting point for a new .NET project

If your project has complex business logic spanning many controllers, a large team, or requires extensive customisation of the MVC pipeline, the traditional controller approach still makes sense. Both coexist in the same application — you can mix them.

Wrapping Up

Minimal APIs are not a replacement for controllers in every scenario. They are a deliberate alternative that prioritises brevity and developer experience for well-scoped APIs. Start with them on your next small service and see how far they take you before adding the controller layer.