Minimal API for Dummies

The traditional MVC approach wraps every endpoint in a Controller class with routing attributes. Minimal API flips that: you define the route and the handler in a single line, with no class required at all.

// ── OLD WAY: MVC Controller ───────────────────
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id) { ... }
}

// ── NEW WAY: Minimal API (Program.cs) ─────────
app.MapGet("/api/products/{id}", (int id) => ...);

// That's it. One line.

Less ceremony means fewer files, faster startup, and an easier on-ramp for beginners. It's the default choice for new .NET 8 projects, microservices, and serverless functions.

// Pros of Minimal API
// ✔ Less boilerplate — no controller classes needed
// ✔ Faster startup — fewer middleware components
// ✔ Easier to learn — one file to understand it all
// ✔ First-class OpenAPI / Swagger support
// ✔ All the same DI, EF Core, Auth that MVC has

// When to stick with MVC controllers
// ✘ Very large team already on MVC
// ✘ Need complex action filters on every endpoint
// ✘ Migrating a huge existing codebase

Run dotnet new webapi -minimal and you get a single Program.cs. Everything starts there. As the project grows you extract groups into separate files — but the shape stays the same.

MyApi/
├── Program.cs          ← entry point, all wiring
├── Models/
│   └── Product.cs      ← plain C# record / class
├── Data/
│   └── AppDbContext.cs ← EF Core DbContext
├── Endpoints/
│   └── ProductEndpoints.cs  ← extracted endpoint groups
└── MyApi.csproj

// dotnet CLI to create:
dotnet new webapi --use-minimal-apis -n MyApi
cd MyApi
dotnet run

WebApplication.CreateBuilder wires up DI and configuration. builder.Build() returns the app. Then you map routes and call app.Run(). That's the whole lifecycle.

// Program.cs — .NET 8
var builder = WebApplication.CreateBuilder(args);
var app     = builder.Build();

app.MapGet("/", () => "Hello, Minimal API!");

app.Run();

// Hit it:
// curl https://localhost:5001/
// → Hello, Minimal API!

Each HTTP verb has its own Map* method. The framework automatically deserialises the JSON body into your C# type on POST / PUT.

// GET — read a resource
app.MapGet("/products",        () => Results.Ok(products));

// POST — create a resource
app.MapPost("/products",       (Product p) => {
    products.Add(p);
    return Results.Created($"/products/{p.Id}", p);
});

// PUT — replace a resource
app.MapPut("/products/{id}",   (int id, Product p) => {
    // update logic...
    return Results.NoContent();
});

// DELETE — remove a resource
app.MapDelete("/products/{id}", (int id) => {
    products.RemoveAll(x => x.Id == id);
    return Results.NoContent();
});

The static Results class gives you typed helpers for every HTTP status. Use them — they produce correct Content-Type headers and status codes automatically.

// ── 200 OK with body ─────────────────────────
return Results.Ok(product);

// ── 201 Created with Location header ─────────
return Results.Created($"/products/{p.Id}", p);

// ── 204 No Content ────────────────────────────
return Results.NoContent();

// ── 400 Bad Request ───────────────────────────
return Results.BadRequest("Name is required.");

// ── 404 Not Found ─────────────────────────────
return Results.NotFound($"Product {id} not found.");

// ── 409 Conflict ──────────────────────────────
return Results.Conflict("SKU already exists.");

// ── Problem Details (RFC 7807) ────────────────
return Results.Problem(
    title:  "Unprocessable entity",
    statusCode: 422);

.NET 9 ships Microsoft.AspNetCore.OpenApi built-in. Annotate endpoints with .WithName() and .WithTags() to get a fully documented API spec automatically.

// Program.cs
builder.Services.AddOpenApi();      // register OpenAPI

var app = builder.Build();

if (app.Environment.IsDevelopment())
    app.MapOpenApi();               // serves /openapi/v1.json

// Annotate endpoints:
app.MapGet("/products/{id}", (int id) => ...)
   .WithName("GetProductById")
   .WithTags("Products")
   .WithSummary("Fetch a single product by ID")
   .Produces<Product>(200)
   .Produces(404);

// Swagger UI (add Scalar package):
// app.MapScalarApiReference();

Wrap a segment in {curly braces} in the route template. The framework automatically parses it to the matching parameter type — int, Guid, string, etc.

// Simple int route param
app.MapGet("/products/{id}", (int id) =>
    db.Products.FindAsync(id));

// Guid route param
app.MapGet("/orders/{orderId:guid}", (Guid orderId) => ...);

// Multiple route params
app.MapGet("/categories/{catId}/products/{prodId}",
    (int catId, int prodId) => ...);

// Constrained route param (only digits, 1-5 chars)
app.MapGet("/codes/{code:alpha:length(1,5)}", (string code) => ...);

// ── Built-in constraints ──────────────────────
// :int  :long  :double  :decimal
// :guid  :bool  :datetime
// :alpha  :minlength(n)  :maxlength(n)  :range(a,b)

Any parameter whose name is not in the route template is treated as a query string value. Make it nullable or give it a default to make it optional.

// GET /products?category=Books&page=2&pageSize=20
app.MapGet("/products", (
    string?  category,   // ?category=Books   (optional)
    int      page     = 1,
    int      pageSize = 20) =>
{
    var query = db.Products.AsQueryable();

    if (category is not null)
        query = query.Where(p => p.Category == category);

    return query
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync();
});

// Nullable bool flag
// GET /products?inStock=true
app.MapGet("/products/search", (bool? inStock) => ...);

Declare a complex type as a parameter and the framework automatically deserialises the JSON body into it. Use a C# record with positional parameters for concise, immutable request DTOs.

// Define the DTO (Data Transfer Object)
public record CreateProductRequest(
    string  Name,
    decimal Price,
    int     Stock,
    string  Category);

// The framework reads the body and maps it
app.MapPost("/products", async (
    CreateProductRequest req,
    AppDbContext         db) =>
{
    var product = new Product
    {
        Name     = req.Name,
        Price    = req.Price,
        Stock    = req.Stock,
        Category = req.Category
    };
    db.Products.Add(product);
    await db.SaveChangesAsync();
    return Results.Created($"/products/{product.Id}", product);
});

// JSON body sent by the client:
// { "name": "Laptop", "price": 999.99, "stock": 5, "category": "Tech" }

Use explicit binding attributes when the name alone isn't enough — inject headers, claim values, or services right in the parameter list.

using Microsoft.AspNetCore.Mvc; // [FromHeader], [FromQuery]

app.MapGet("/me", (
    [FromHeader(Name = "X-Correlation-Id")] string? correlationId,
    [FromServices] ILogger<Program>              logger,
    HttpContext                                   ctx) =>
{
    var userId = ctx.User.FindFirst("sub")?.Value;
    logger.LogInformation("User {Id} called /me", userId);

    return Results.Ok(new { UserId = userId, correlationId });
});

// [FromQuery] forces query-string even if name clashes
app.MapGet("/search", ([FromQuery] string q) => ...);

// Inject CancellationToken for long operations
app.MapGet("/slow", async (CancellationToken ct) =>
{
    await Task.Delay(5000, ct);
    return Results.Ok("done");
});

MapGroup shares a common prefix and lets you attach middleware (auth, rate-limiting) to a whole family of endpoints without repeating yourself.

// All /api/v1/products/* endpoints in one group
var products = app.MapGroup("/api/v1/products")
                  .WithTags("Products")
                  .RequireAuthorization();   // all routes need a valid JWT

products.MapGet("/",     GetAll);
products.MapGet("/{id}", GetById);
products.MapPost("/",    Create);
products.MapPut("/{id}", Update);
products.MapDelete("/{id}", Delete);

// Extract to a static class for large APIs
public static class ProductEndpoints
{
    public static IEndpointRouteBuilder Map(IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v1/products");
        group.MapGet("/", GetAll);
        // ...
        return app;
    }
}

Pick the right lifetime or you'll get subtle bugs — especially the "captive dependency" trap where a Singleton captures a Scoped service.

// ── Transient — new instance every injection
builder.Services.AddTransient<IEmailSender, SmtpEmailSender>();

// ── Scoped — one instance per HTTP request
builder.Services.AddScoped<IProductRepository, ProductRepository>();
builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

// ── Singleton — one instance for the app's lifetime
builder.Services.AddSingleton<ICacheService, MemoryCacheService>();

// ── Options pattern for config ────────────────
builder.Services.Configure<JwtSettings>(
    builder.Configuration.GetSection("Jwt"));

// ── Common built-ins ──────────────────────────
builder.Services.AddMemoryCache();
builder.Services.AddHttpClient();
builder.Services.AddLogging();

The framework inspects parameter types at startup. Any type registered in the DI container is resolved automatically — no attribute, no constructor, no controller.

// AppDbContext + ILogger injected automatically
app.MapGet("/products/{id}", async (
    int            id,
    AppDbContext   db,
    ILogger<Program> log) =>
{
    log.LogInformation("Fetching product {Id}", id);

    var product = await db.Products.FindAsync(id);
    return product is null
        ? Results.NotFound()
        : Results.Ok(product);
});

// Custom service injected
app.MapPost("/orders", async (
    CreateOrderRequest req,
    IOrderService      svc,
    CancellationToken  ct) =>
{
    var order = await svc.PlaceOrderAsync(req, ct);
    return Results.Created($"/orders/{order.Id}", order);
});

Fat lambdas are hard to test. Extract business logic into a service class, inject it, and keep the endpoint down to 5 lines or fewer.

// ── Interface (Application layer) ─────────────
public interface IProductService
{
    Task<Product?>     GetAsync(int id, CancellationToken ct);
    Task<Product>      CreateAsync(CreateProductRequest req, CancellationToken ct);
    Task<bool>         DeleteAsync(int id, CancellationToken ct);
}

// ── Endpoint stays thin ───────────────────────
app.MapGet("/products/{id}", async (
    int id, IProductService svc, CancellationToken ct) =>
{
    var product = await svc.GetAsync(id, ct);
    return product is null ? Results.NotFound() : Results.Ok(product);
});

app.MapPost("/products", async (
    CreateProductRequest req, IProductService svc, CancellationToken ct) =>
{
    var created = await svc.CreateAsync(req, ct);
    return Results.Created($"/products/{created.Id}", created);
});

Register the DbContext once in Program.cs, then inject it anywhere. EF Core handles connection pooling, change tracking, and migrations automatically.

// ── Model ─────────────────────────────────────
public class Product
{
    public int     Id       { get; set; }
    public string  Name     { get; set; } = "";
    public decimal Price    { get; set; }
    public string  Category { get; set; } = "";
}

// ── DbContext ─────────────────────────────────
public class AppDbContext(DbContextOptions<AppDbContext> opts)
    : DbContext(opts)
{
    public DbSet<Product> Products => Set<Product>();
}

// ── Program.cs: register ──────────────────────
builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseSqlServer(
        builder.Configuration.GetConnectionString("Default")));

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

app.MapGet("/products/{id}", async (int id, AppDbContext db) =>
    await db.Products.FindAsync(id)
        is Product p ? Results.Ok(p) : Results.NotFound());

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

app.MapPut("/products/{id}", async (int id, Product input, AppDbContext db) => {
    var p = await db.Products.FindAsync(id);
    if (p is null) return Results.NotFound();
    p.Name  = input.Name;
    p.Price = input.Price;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/products/{id}", async (int id, AppDbContext db) => {
    if (await db.Products.FindAsync(id) is not Product p) return Results.NotFound();
    db.Products.Remove(p);
    await db.SaveChangesAsync();
    return Results.NoContent();
});

Migrations translate C# model changes into SQL scripts. Run them from the CLI — the database schema stays in sync with your code automatically.

// Add EF Core tools once (global)
dotnet tool install -g dotnet-ef

// Add required packages to your project
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design

// Create the first migration
dotnet ef migrations add InitialCreate

// Apply it to the database
dotnet ef database update

// ── Apply migrations on startup (dev only) ────
// In Program.cs:
using var scope = app.Services.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
await db.Database.MigrateAsync();

// ── Typical migration workflow ─────────────────
// 1. Change your model class
// 2. dotnet ef migrations add AddCategoryColumn
// 3. dotnet ef database update

When you need hand-tuned SQL for performance-critical reads, Dapper maps result sets to C# objects in one line — with zero overhead and full parameterisation.

// NuGet: dotnet add package Dapper
// NuGet: dotnet add package Microsoft.Data.SqlClient

builder.Services.AddScoped<IDbConnection>(_ =>
    new SqlConnection(
        builder.Configuration.GetConnectionString("Default")));

// Inject IDbConnection into the endpoint
app.MapGet("/products/search", async (
    string       keyword,
    IDbConnection db) =>
{
    var sql = """
        SELECT Id, Name, Price, Category
        FROM   dbo.Products
        WHERE  Name LIKE @Keyword
        ORDER  BY Name
        """;

    var results = await db.QueryAsync<Product>(sql,
        new { Keyword = $"%{keyword}%" });

    return Results.Ok(results);
});

// Multi-mapping (JOIN result → two objects)
var orders = await db.QueryAsync<Order, Customer, Order>(
    sql, (o, c) => { o.Customer = c; return o; },
    splitOn: "CustomerId");

Define validation rules in a dedicated AbstractValidator<T> class, register it as a service, and inject it into the endpoint. Clean, testable, zero reflection magic.

// dotnet add package FluentValidation.DependencyInjectionExtensions

public record CreateProductRequest(string Name, decimal Price, int Stock);

public class CreateProductValidator : AbstractValidator<CreateProductRequest>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty().WithMessage("Name is required.")
            .MaximumLength(200);

        RuleFor(x => x.Price)
            .GreaterThan(0).WithMessage("Price must be positive.");

        RuleFor(x => x.Stock)
            .GreaterThanOrEqualTo(0);
    }
}

// Register all validators in the assembly
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

// Use in endpoint
app.MapPost("/products", async (
    CreateProductRequest       req,
    IValidator<CreateProductRequest> validator,
    AppDbContext               db) =>
{
    var result = await validator.ValidateAsync(req);
    if (!result.IsValid)
        return Results.ValidationProblem(result.ToDictionary());

    var product = new Product { Name = req.Name, Price = req.Price };
    db.Products.Add(product);
    await db.SaveChangesAsync();
    return Results.Created($"/products/{product.Id}", product);
});

One central place catches every unhandled exception and returns a consistent RFC 7807 Problem Details response — no try/catch scattered across endpoints.

// ── .NET 8: UseExceptionHandler ───────────────
app.UseExceptionHandler(errApp => errApp.Run(async ctx =>
{
    var ex  = ctx.Features.Get<IExceptionHandlerFeature>()?.Error;
    var log = ctx.RequestServices.GetRequiredService<ILogger<Program>>();
    log.LogError(ex, "Unhandled exception");

    ctx.Response.StatusCode  = StatusCodes.Status500InternalServerError;
    ctx.Response.ContentType = "application/problem+json";

    await ctx.Response.WriteAsJsonAsync(new
    {
        type   = "https://tools.ietf.org/html/rfc7807",
        title  = "An unexpected error occurred.",
        status = 500,
        traceId = ctx.TraceIdentifier
    });
}));

// ── .NET 8 also ships IExceptionHandler ───────
public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> log)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext ctx, Exception ex, CancellationToken ct)
    {
        log.LogError(ex, "Unhandled exception");
        ctx.Response.StatusCode = 500;
        await ctx.Response.WriteAsJsonAsync(
            new ProblemDetails { Title = "Server error", Status = 500 }, ct);
        return true;
    }
}

// Register:
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();
app.UseExceptionHandler();

Endpoint filters run before and after the handler — perfect for extracting validation into a reusable pipeline step that can be applied to multiple endpoints.

// Generic validation filter
public class ValidationFilter<T>(IValidator<T> validator)
    : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext ctx,
        EndpointFilterDelegate          next)
    {
        var arg = ctx.Arguments.OfType<T>().FirstOrDefault();
        if (arg is not null)
        {
            var result = await validator.ValidateAsync(arg);
            if (!result.IsValid)
                return Results.ValidationProblem(result.ToDictionary());
        }
        return await next(ctx);
    }
}

// Apply to an endpoint (or entire group)
app.MapPost("/products", async (CreateProductRequest req, AppDbContext db) =>
{
    // Validation already ran — req is guaranteed valid here
    var p = new Product { Name = req.Name, Price = req.Price };
    db.Products.Add(p);
    await db.SaveChangesAsync();
    return Results.Created($"/products/{p.Id}", p);
})
.AddEndpointFilter<ValidationFilter<CreateProductRequest>>();

Add the package, configure the secret key, register middleware, then lock endpoints with .RequireAuthorization(). The framework validates the token and populates HttpContext.User automatically.

// dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

// ── Program.cs ────────────────────────────────
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(opt =>
    {
        opt.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer           = true,
            ValidateAudience         = true,
            ValidateLifetime         = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer              = builder.Configuration["Jwt:Issuer"],
            ValidAudience            = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey         = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!))
        };
    });

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();   // must come before UseAuthorization
app.UseAuthorization();

// ── Secure individual endpoints ───────────────
app.MapGet("/profile", (HttpContext ctx) =>
{
    var userId = ctx.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    return Results.Ok(new { userId });
})
.RequireAuthorization();

// ── Secure an entire group ────────────────────
var admin = app.MapGroup("/admin").RequireAuthorization("AdminPolicy");
admin.MapGet("/stats", () => Results.Ok(GetStats()));

The login endpoint validates credentials, builds a claims identity, signs it with the secret key, and returns the token string. The client sends it back as Authorization: Bearer <token> on every subsequent request.

public record LoginRequest(string Email, string Password);

app.MapPost("/auth/login", (LoginRequest req, IConfiguration cfg) =>
{
    // Replace with real credential check
    if (req.Email != "admin@demo.com" || req.Password != "secret")
        return Results.Unauthorized();

    var claims = new[]
    {
        new Claim(ClaimTypes.NameIdentifier, "1"),
        new Claim(ClaimTypes.Email,          req.Email),
        new Claim(ClaimTypes.Role,           "Admin")
    };

    var key   = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(cfg["Jwt:Key"]!));
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

    var token = new JwtSecurityToken(
        issuer:   cfg["Jwt:Issuer"],
        audience: cfg["Jwt:Audience"],
        claims:   claims,
        expires:  DateTime.UtcNow.AddHours(1),
        signingCredentials: creds);

    return Results.Ok(new
    {
        token = new JwtSecurityTokenHandler().WriteToken(token)
    });
})
.AllowAnonymous()
.WithTags("Auth");

Named policies let you express complex rules once and reference them by name on any endpoint or group — far cleaner than sprinkling attribute parameters everywhere.

builder.Services.AddAuthorization(opt =>
{
    // Simple role check
    opt.AddPolicy("AdminOnly", p => p.RequireRole("Admin"));

    // Claim-based policy
    opt.AddPolicy("PremiumUser", p =>
        p.RequireClaim("subscription", "premium", "enterprise"));

    // Combined — authenticated AND UK-based
    opt.AddPolicy("UKAdmin", p =>
    {
        p.RequireAuthenticatedUser();
        p.RequireRole("Admin");
        p.RequireClaim("country", "UK");
    });
});

// Apply by name
app.MapDelete("/products/{id}", ...)
   .RequireAuthorization("AdminOnly");

app.MapGet("/reports", ...)
   .RequireAuthorization("PremiumUser");

// Read role inside an endpoint
app.MapGet("/whoami", (HttpContext ctx) =>
{
    var role = ctx.User.FindFirst(ClaimTypes.Role)?.Value;
    return Results.Ok(new { role });
})
.RequireAuthorization();

Keep this tab open. When in doubt, find the line below and copy it.

// ── Endpoint verbs ────────────────────────────
app.MapGet(pattern,    handler);
app.MapPost(pattern,   handler);
app.MapPut(pattern,    handler);
app.MapPatch(pattern,  handler);
app.MapDelete(pattern, handler);

// ── Parameter sources (automatic) ────────────
// {id}           → route
// ?page=2        → query string
// { "name":... } → JSON body (complex type)
// HttpContext     → special type, always injected
// IService        → from DI container

// ── Results helpers ───────────────────────────
Results.Ok(value)                  // 200
Results.Created(uri, value)        // 201
Results.Accepted()                 // 202
Results.NoContent()                // 204
Results.BadRequest("msg")          // 400
Results.Unauthorized()             // 401
Results.Forbid()                   // 403
Results.NotFound()                 // 404
Results.Conflict()                 // 409
Results.ValidationProblem(errors)  // 422
Results.Problem(title, status:500) // 500

// ── Endpoint metadata ─────────────────────────
.WithName("GetProduct")
.WithTags("Products")
.WithSummary("...")
.Produces<T>(200)
.RequireAuthorization("PolicyName")
.AllowAnonymous()
.AddEndpointFilter<MyFilter>()

// ── Groups ────────────────────────────────────
var g = app.MapGroup("/api/v1/products")
           .WithTags("Products")
           .RequireAuthorization();

// ── Middleware order (IMPORTANT!) ─────────────
app.UseHttpsRedirection();
app.UseAuthentication();  // ← before Authorization
app.UseAuthorization();
// app.MapXxx() calls here