Minimal APIs in ASP.NET Core — Build Fast, Lean REST Endpoints

// Program.cs — a complete, runnable Minimal API
// Requires: dotnet new web -o ProductApi
// No controllers, no separate Startup.cs, no folder structure required.

var builder = WebApplication.CreateBuilder(args);

// Register services into the DI container BEFORE calling Build()
builder.Services.AddEndpointsApiExplorer(); // Enables OpenAPI endpoint discovery
builder.Services.AddSwaggerGen();           // Wires up Swagger UI

var app = builder.Build();

// Middleware runs in the order you register it — this matters!
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();    // Serves the OpenAPI JSON spec at /swagger/v1/swagger.json
    app.UseSwaggerUI(); // Serves the browser UI at /swagger
}

// MapGet registers a GET handler for the route "/"
// The lambda IS the handler — no controller needed
app.MapGet("/", () => "Product Catalogue API is running!");

// MapGet with a route parameter — {id} is captured and injected automatically
// ASP.NET Core infers the int type from the parameter name and type annotation
app.MapGet("/products/{id}", (int id) =>
{
    // In a real app this would call a service; here we prove the binding works
    return Results.Ok(new { ProductId = id, Name = $"Product #{id}", Price = 9.99m });
});

// MapPost accepts a JSON body — the [FromBody] attribute is inferred automatically
// The record type is deserialized from the request body using System.Text.Json
app.MapPost("/products", (CreateProductRequest request) =>
{
    // Results.Created sets HTTP 201 and the Location header — correct REST semantics
    return Results.Created($"/products/42", new { Id = 42, request.Name, request.Price });
});

app.Run();

// Define your request/response models — keep them close to where they're used
// Using records gives you immutability and value equality for free
public record CreateProductRequest(string Name, decimal Price);

// ── ProductEndpoints.cs ──────────────────────────────────────────────────────
// Extension method that groups all /products endpoints in one place.
// Program.cs calls app.MapProductEndpoints() — keeping the entry file clean.

using Microsoft.AspNetCore.Http.HttpResults; // Typed Results — strongly-typed return types

public static class ProductEndpoints
{
    public static void MapProductEndpoints(this WebApplication app)
    {
        // RouteGroupBuilder applies the prefix AND any shared middleware to every endpoint below
        var group = app.MapGroup("/products")
                       .WithTags("Products")       // Groups endpoints in Swagger UI
                       .WithOpenApi();             // Generates OpenAPI metadata automatically

        group.MapGet("/",    GetAllProducts);
        group.MapGet("/{id:int}", GetProductById); // :int constrains the route — 404 on non-int
        group.MapPost("/",   CreateProduct);
        group.MapPut("/{id:int}",    UpdateProduct);
        group.MapDelete("/{id:int}", DeleteProduct);
    }

    // Handler methods are static — no allocations for a class instance per request
    // IProductService is resolved from DI; int id comes from the route segment
    static async Task<Ok<IEnumerable<Product>>> GetAllProducts(
        IProductService productService)
    {
        var products = await productService.GetAllAsync();
        return TypedResults.Ok(products); // TypedResults gives compile-time HTTP status verification
    }

    static async Task<Results<Ok<Product>, NotFound>> GetProductById(
        int id,
        IProductService productService)
    {
        var product = await productService.GetByIdAsync(id);

        // Pattern match on null — returns 404 if not found, 200 with body if found
        return product is null
            ? TypedResults.NotFound()
            : TypedResults.Ok(product);
    }

    static async Task<Created<Product>> CreateProduct(
        CreateProductRequest request,       // Bound from JSON request body
        IProductService productService,
        LinkGenerator linkGenerator,        // Built-in service to generate URLs
        HttpContext httpContext)
    {
        var created = await productService.CreateAsync(request);

        // Generate the Location header pointing to the new resource — correct REST
        var location = linkGenerator.GetPathByName(httpContext, "GetProductById",
                                                   new { id = created.Id });
        return TypedResults.Created(location, created);
    }

    static async Task<Results<NoContent, NotFound>> UpdateProduct(
        int id,
        UpdateProductRequest request,
        IProductService productService)
    {
        var success = await productService.UpdateAsync(id, request);
        return success ? TypedResults.NoContent() : TypedResults.NotFound();
    }

    static async Task<Results<NoContent, NotFound>> DeleteProduct(
        int id,
        IProductService productService)
    {
        var success = await productService.DeleteAsync(id);
        return success ? TypedResults.NoContent() : TypedResults.NotFound();
    }
}

// ── Program.cs (the clean version) ──────────────────────────────────────────
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Register your domain services — Minimal APIs use the SAME DI system as controllers
builder.Services.AddScoped<IProductService, ProductService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// One line per feature area — Program.cs stays readable at any scale
app.MapProductEndpoints();

app.Run();

// ── Domain models (simplified for clarity) ───────────────────────────────────
public record Product(int Id, string Name, decimal Price, int StockCount);
public record CreateProductRequest(string Name, decimal Price, int StockCount);
public record UpdateProductRequest(string Name, decimal Price, int StockCount);

public interface IProductService
{
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product?> GetByIdAsync(int id);
    Task<Product>  CreateAsync(CreateProductRequest request);
    Task<bool>     UpdateAsync(int id, UpdateProductRequest request);
    Task<bool>     DeleteAsync(int id);
}

// ── ValidationFilter.cs ─────────────────────────────────────────────────────
// A generic endpoint filter that validates any request model using FluentValidation.
// Add NuGet: FluentValidation.AspNetCore

using FluentValidation;

public class ValidationFilter<TRequest> : IEndpointFilter
{
    private readonly IValidator<TRequest> _validator;

    public ValidationFilter(IValidator<TRequest> validator)
    {
        _validator = validator;
    }

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        // Find the argument that matches our request type in the handler's parameter list
        var request = context.Arguments
                             .OfType<TRequest>()
                             .FirstOrDefault();

        if (request is null)
            return Results.BadRequest("Request body is missing.");

        var validationResult = await _validator.ValidateAsync(request);

        if (!validationResult.IsValid)
        {
            // Return a structured 400 with all validation errors — client-friendly
            var errors = validationResult.Errors
                .GroupBy(e => e.PropertyName)
                .ToDictionary(
                    group => group.Key,
                    group => group.Select(e => e.ErrorMessage).ToArray()
                );

            return Results.ValidationProblem(errors); // Returns RFC 7807 Problem Details
        }

        // Validation passed — call the next filter or the actual handler
        return await next(context);
    }
}

// ── CreateProductRequestValidator.cs ─────────────────────────────────────────
public class CreateProductRequestValidator : AbstractValidator<CreateProductRequest>
{
    public CreateProductRequestValidator()
    {
        RuleFor(r => r.Name)
            .NotEmpty().WithMessage("Product name is required.")
            .MaximumLength(100).WithMessage("Name cannot exceed 100 characters.");

        RuleFor(r => r.Price)
            .GreaterThan(0).WithMessage("Price must be greater than zero.");

        RuleFor(r => r.StockCount)
            .GreaterThanOrEqualTo(0).WithMessage("Stock count cannot be negative.");
    }
}

// ── How to wire it up in ProductEndpoints.cs ─────────────────────────────────
// Apply the filter to only the POST endpoint — surgical, not global
group.MapPost("/", CreateProduct)
     .AddEndpointFilter<ValidationFilter<CreateProductRequest>>();
     // That's it. The handler stays clean.

// ── Program.cs additions for global error handling ───────────────────────────
builder.Services.AddProblemDetails(); // Registers the RFC 7807 Problem Details formatter

// Register all FluentValidation validators from the current assembly automatically
builder.Services.AddValidatorsFromAssemblyContaining<CreateProductRequestValidator>();

// ...

var app = builder.Build();

// UseExceptionHandler MUST come before endpoint mapping
// In .NET 8+, this one-liner handles all unhandled exceptions as Problem Details
app.UseExceptionHandler();
app.UseStatusCodePages(); // Turns empty 404/405 responses into Problem Details too

// ── Testing the validation (curl example) ────────────────────────────────────
// curl -X POST https://localhost:5001/products \
//      -H 'Content-Type: application/json' \
//      -d '{"name": "", "price": -5, "stockCount": -1}'

// Demonstrating auth, rate limiting, and output caching on Minimal API endpoints
// These show Minimal APIs can handle production concerns — not just toy examples

// ── Program.cs service registrations ─────────────────────────────────────────
builder.Services.AddAuthentication().AddJwtBearer(); // JWT auth in one line
builder.Services.AddAuthorization();

builder.Services.AddOutputCache(options =>
{
    // Define a named cache policy — endpoints opt in by name
    options.AddPolicy("ProductCachePolicy", policyBuilder =>
        policyBuilder.Expire(TimeSpan.FromSeconds(30))
                     .Tag("products")); // Tag lets us invalidate by group later
});

builder.Services.AddRateLimiter(options =>
{
    // Fixed window: max 100 requests per minute per IP address
    options.AddFixedWindowLimiter("ApiRateLimit", limiterOptions =>
    {
        limiterOptions.PermitLimit = 100;
        limiterOptions.Window = TimeSpan.FromMinutes(1);
        limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        limiterOptions.QueueLimit = 5; // Buffer up to 5 excess requests, then 503
    });

    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
});

// ── app middleware — ORDER MATTERS ────────────────────────────────────────────
app.UseAuthentication(); // Must come before UseAuthorization
app.UseAuthorization();
app.UseOutputCache();
app.UseRateLimiter();

// ── Endpoint with all production concerns attached ───────────────────────────
var group = app.MapGroup("/products")
               .WithTags("Products")
               .RequireAuthorization()        // Every endpoint in this group needs a valid JWT
               .RequireRateLimiting("ApiRateLimit"); // Apply rate limit to the whole group

// This specific endpoint also uses output caching — expensive DB read cached for 30s
group.MapGet("/", async (IProductService productService) =>
    {
        var products = await productService.GetAllAsync();
        return TypedResults.Ok(products);
    })
    .CacheOutput("ProductCachePolicy"); // Only GET /products is cached, not the whole group

// Cache invalidation when a product is created
group.MapPost("/", async (
    CreateProductRequest request,
    IProductService productService,
    IOutputCacheStore cacheStore,          // Inject the cache store directly
    CancellationToken cancellationToken) =>
{
    var created = await productService.CreateAsync(request);

    // Invalidate all cached responses tagged "products" so GET / reflects the new item
    await cacheStore.EvictByTagAsync("products", cancellationToken);

    return TypedResults.Created($"/products/{created.Id}", created);
})
.AddEndpointFilter<ValidationFilter<CreateProductRequest>>();