Building Production-Ready APIs with .NET: From Minimal APIs to Clean Architecture

You’ve spun up a Minimal API in .NET, added a few endpoints, and suddenly you’re staring at a Program.cs file with 500 lines of tangled business logic. Every senior engineer has been there—the framework makes getting started trivially easy, but production-ready is a different beast entirely.

The seduction is real. Microsoft’s Minimal APIs promise lean, expressive endpoints without the ceremony of controllers. And they deliver. A functioning API in under a dozen lines of code. No Startup.cs. No dependency injection boilerplate. Just app.MapGet and you’re shipping features.

Then reality sets in. That quick prototype becomes the foundation for actual business logic. Validation creeps in. Error handling. Database calls. Authentication checks. Authorization policies. Logging. Suddenly your elegant one-liner has metastasized into an anonymous function spanning 80 lines, and you’ve got fifteen of them competing for space in a single file.

The real problem isn’t Minimal APIs—it’s the absence of architectural guardrails. Traditional MVC controllers, for all their verbosity, imposed structure. They forced you to think in terms of separation, even if you didn’t fully understand why. Minimal APIs hand you a blank canvas and trust you to paint responsibly. Most of us don’t.

This isn’t an argument against Minimal APIs. They’re the right choice for certain applications and remain the right choice at scale—if you evolve your architecture deliberately. The difference between a prototype that collapses under its own weight and a production system that scales with your team comes down to recognizing the inflection points and knowing which patterns to reach for.

Let’s start with the trap itself: understanding exactly how simple becomes complex, and why the same flexibility that makes Minimal APIs powerful also makes them dangerous.

The Minimal API Trap: Why Simple Becomes Complex

Minimal APIs arrived in .NET 6 with a compelling promise: define endpoints in a few lines, ship fast, iterate faster. The syntax is elegant. The friction is low. And therein lies the problem.

app.MapGet("/users/{id}", (int id, UserService service) => service.GetUser(id));

This single line handles routing, parameter binding, and dependency injection. It’s beautiful for a proof of concept. It’s dangerous for a production system.

The Seduction of Simplicity

Teams adopt Minimal APIs because they eliminate ceremony. No controllers, no action methods, no attribute routing—just lambdas and results. The first ten endpoints write themselves. The demo works. Stakeholders are impressed.

Then reality sets in.

Endpoint number fifteen needs validation. Number twenty requires authorization that differs from the others. Number thirty shares business logic with number twelve, so someone copies the lambda body. Number forty needs different error handling for mobile clients versus web clients.

Six months later, Program.cs spans 800 lines. Business logic lives inside route handlers. Validation happens inconsistently. Error responses vary by whoever wrote each endpoint. The codebase that felt lightweight now carries the weight of every shortcut taken along the way.

Recognizing the Inflection Point

The transition from “simple API” to “architectural liability” rarely announces itself. Watch for these signals:

Cross-cutting concerns multiply. When you find yourself copying authentication checks, logging calls, or try-catch blocks across endpoints, you’ve outgrown inline handlers.

Business logic escapes its boundaries. The moment a lambda does more than orchestrate—when it contains conditionals, calculations, or multiple service calls—you’re embedding domain logic in your routing layer.

Testing becomes painful. If testing an endpoint requires mocking HTTP contexts or reconstructing the entire request pipeline, your design is fighting your test framework.

New developers struggle. When onboarding requires explaining “why we do it this way in these endpoints but differently in those endpoints,” consistency has eroded.

When Minimal APIs Remain the Right Choice

Not every API needs architectural scaffolding. Minimal APIs excel for microservices with genuinely narrow scope, backend-for-frontend layers that aggregate other services, internal tools with limited lifespans, and prototypes that will be rewritten before production.

The key distinction: Minimal APIs work when the API stays minimal. The trap springs when the scope grows but the architecture doesn’t.

💡 Pro Tip: If your API will support more than one client application or survive longer than one development cycle, invest in structure from the start. Retrofitting architecture costs more than building it incrementally.

The question isn’t whether Minimal APIs are good or bad—they’re a tool. The question is whether your project will remain simple enough to justify the simplicity. For most production systems, the answer emerges quickly: structure pays dividends.

Let’s examine how to introduce that structure without abandoning what makes Minimal APIs appealing.

Structuring Minimal APIs for Growth

A single Program.cs file works fine for a demo, but production APIs demand better organization. The good news: Minimal APIs provide first-class primitives for structuring code without sacrificing their lightweight nature. Understanding these patterns early prevents the architectural debt that accumulates when rapid prototypes evolve into production systems.

Endpoint Grouping with MapGroup

The MapGroup method creates a logical container for related endpoints, eliminating repetitive route prefixes and enabling shared configuration:

var app = builder.Build();

var api = app.MapGroup("/api");

var products = api.MapGroup("/products")
    .RequireAuthorization()
    .WithTags("Products");

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

Each endpoint inherits the /api/products prefix, authorization requirement, and OpenAPI tag. This approach scales cleanly—add ten more endpoints and the configuration stays in one place. Groups can also be nested, allowing you to create hierarchies like /api/v1/products without duplicating configuration at each level.

Beyond route prefixes, groups excel at applying cross-cutting concerns. Need rate limiting on all product endpoints? Add .RequireRateLimiting("standard") to the group. Want different authorization policies for read versus write operations? Create separate groups within the same parent. This composability makes groups the foundation of well-organized Minimal APIs.

Extracting Handlers into Dedicated Endpoint Classes

Static methods in Program.cs become unwieldy fast. Extract handlers into dedicated classes that encapsulate their dependencies and related logic:

public static class ProductEndpoints
{
    public static RouteGroupBuilder MapProductEndpoints(this RouteGroupBuilder group)
    {
        group.MapGet("/", GetAll);
        group.MapGet("/{id:int}", GetById);
        group.MapPost("/", Create);
        return group;
    }

    private static async Task<Ok<List<ProductDto>>> GetAll(
        IProductRepository repository,
        CancellationToken ct)
    {
        var products = await repository.GetAllAsync(ct);
        return TypedResults.Ok(products);
    }

    private static async Task<Results<Ok<ProductDto>, NotFound>> GetById(
        int id,
        IProductRepository repository,
        CancellationToken ct)
    {
        var product = await repository.GetByIdAsync(id, ct);
        return product is not null
            ? TypedResults.Ok(product)
            : TypedResults.NotFound();
    }

    private static async Task<Created<ProductDto>> Create(
        CreateProductRequest request,
        IProductRepository repository,
        CancellationToken ct)
    {
        var product = await repository.CreateAsync(request, ct);
        return TypedResults.Created($"/api/products/{product.Id}", product);
    }
}

Registration becomes a one-liner:

api.MapGroup("/products")
    .MapProductEndpoints()
    .RequireAuthorization();

The TypedResults class provides compile-time safety for response types. The Results<T1, T2> return type tells OpenAPI exactly which responses the endpoint can produce—no manual attributes required. This pattern also improves testability since each handler method can be unit tested in isolation by passing mock dependencies directly.

Dependency Injection Patterns That Scale

Minimal API handlers resolve dependencies directly from method parameters. Structure your services to take advantage of this automatic resolution:

builder.Services.AddScoped<IProductRepository, ProductRepository>();
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddSingleton<ICacheService, RedisCacheService>();
builder.Services.AddTransient<IEmailService, SmtpEmailService>();

For complex operations spanning multiple services, introduce application services rather than bloating handlers with orchestration logic:

public class OrderService(
    IOrderRepository orders,
    IProductRepository products,
    IEmailService email)
{
    public async Task<Result<OrderDto>> PlaceOrderAsync(
        PlaceOrderRequest request,
        CancellationToken ct)
    {
        var product = await products.GetByIdAsync(request.ProductId, ct);
        if (product is null)
            return Result.Failure<OrderDto>("Product not found");

        var order = await orders.CreateAsync(request, ct);
        await email.SendOrderConfirmationAsync(order, ct);

        return Result.Success(order);
    }
}

This pattern keeps handlers thin—they validate input, call the appropriate service, and map results to HTTP responses. The application service layer becomes the natural home for business logic, transaction boundaries, and cross-service coordination.

💡 Pro Tip: Use primary constructors (C# 12) for service classes. They reduce boilerplate and make dependencies immediately visible at the class declaration.

Project Structure for Maintainability

A maintainable structure emerges naturally from these patterns:

src/
  Api/
    Endpoints/
      ProductEndpoints.cs
      OrderEndpoints.cs
    Program.cs
  Application/
    Services/
    Interfaces/
  Infrastructure/
    Repositories/
    Data/

This isn’t Clean Architecture yet—it’s organized Minimal APIs. The separation provides clear boundaries without premature abstraction. As your application grows, this structure accommodates additional complexity: filters go in a Filters/ directory, custom binding logic in Binding/, and shared response types in Models/. The key is letting structure emerge from need rather than imposing it upfront.

With endpoints organized and dependencies properly injected, the next challenge surfaces: what happens when invalid requests hit your API? Proper validation and error handling prevent implementation details from leaking to clients.

Request Validation and Error Handling That Doesn’t Leak

A production API reveals its maturity through how it handles invalid input and unexpected failures. Leaking stack traces to clients is a security risk that exposes implementation details attackers can exploit. Returning inconsistent error formats breaks client integrations and forces frontend teams to write defensive parsing logic. Poor logging turns debugging into archaeology, where you spend hours correlating timestamps across disparate log files. This section addresses all three concerns with patterns that scale from a single service to a distributed system.

FluentValidation for Complex Rules

While Data Annotations work for simple cases like [Required] or [StringLength], real-world validation demands more sophistication. Business rules often span multiple properties, require database lookups, or change based on context. FluentValidation provides a fluent, testable approach to validation logic that keeps your DTOs clean and your rules maintainable.

public class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderValidator(IInventoryService inventory)
    {
        RuleFor(x => x.CustomerId)
            .NotEmpty()
            .WithMessage("Customer ID is required");

        RuleFor(x => x.Items)
            .NotEmpty()
            .WithMessage("Order must contain at least one item");

        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.Quantity)
                .GreaterThan(0)
                .LessThanOrEqualTo(100);

            item.RuleFor(i => i.ProductId)
                .MustAsync(async (id, ct) => await inventory.ExistsAsync(id, ct))
                .WithMessage("Product not found");
        });
    }
}

The constructor injection of IInventoryService demonstrates a key advantage: validators can access any registered service. This enables async database checks, external API validation, or business rule engines without polluting your controllers. Each validator becomes a focused, unit-testable class.

Register validators automatically using assembly scanning to avoid manual registration of every validator:

builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>();
builder.Services.AddScoped<IValidationService, ValidationService>();

Global Exception Handling with ProblemDetails

.NET 7+ includes built-in ProblemDetails support that standardizes error responses per RFC 7807. This specification defines a consistent JSON structure for HTTP API errors, which clients can parse predictably regardless of which endpoint failed. Configure it to catch unhandled exceptions without exposing internals:

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = context =>
    {
        context.ProblemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? context.HttpContext.TraceIdentifier;
    };
});

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

The custom exception handler maps domain exceptions to appropriate HTTP responses while sanitizing internal details:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken ct)
    {
        _logger.LogError(exception, "Unhandled exception occurred");

        var problemDetails = exception switch
        {
            ValidationException ex => new ProblemDetails
            {
                Status = 400,
                Title = "Validation Failed",
                Detail = string.Join("; ", ex.Errors.Select(e => e.ErrorMessage))
            },
            NotFoundException => new ProblemDetails
            {
                Status = 404,
                Title = "Resource Not Found"
            },
            _ => new ProblemDetails
            {
                Status = 500,
                Title = "An error occurred",
                Detail = "An internal error occurred. Please try again later."
            }
        };

        context.Response.StatusCode = problemDetails.Status ?? 500;
        await context.Response.WriteAsJsonAsync(problemDetails, ct);
        return true;
    }
}

Notice how the 500 error case provides a generic message rather than exposing exception.Message. The full exception is logged server-side where you can access it, while clients receive only what they need to display a user-friendly error.

💡 Pro Tip: Never include exception.Message or stack traces in production responses for 500 errors. Log them server-side with the correlation ID so you can trace issues without exposing implementation details. Attackers routinely probe APIs for stack traces that reveal framework versions, file paths, and database structures.

Structured Logging with Correlation IDs

When a request fails in production, you need to trace it across services. A single user action might touch an API gateway, authentication service, order service, and payment processor. Without correlation, you’re left matching timestamps and hoping the clocks are synchronized. Add correlation ID middleware that threads through all log entries:

public class CorrelationIdMiddleware
{
    private readonly RequestDelegate _next;
    private const string CorrelationHeader = "X-Correlation-Id";

    public CorrelationIdMiddleware(RequestDelegate next) => _next = next;

    public async Task InvokeAsync(HttpContext context)
    {
        var correlationId = context.Request.Headers[CorrelationHeader].FirstOrDefault()
            ?? Guid.NewGuid().ToString();

        context.Response.Headers[CorrelationHeader] = correlationId;

        using (LogContext.PushProperty("CorrelationId", correlationId))
        {
            await _next(context);
        }
    }
}

The middleware respects incoming correlation IDs from upstream services while generating new ones for fresh requests. This preserves traceability across service boundaries in microservice architectures.

Configure Serilog to include this property in every log entry:

builder.Host.UseSerilog((context, config) => config
    .ReadFrom.Configuration(context.Configuration)
    .Enrich.FromLogContext()
    .WriteTo.Console(outputTemplate:
        "[{Timestamp:HH:mm:ss} {Level:u3}] {CorrelationId} {Message:lj}{NewLine}{Exception}"));

Clients receive a correlation ID in the response header. When they report an issue, you search logs by that ID and see the complete request lifecycle—validation failures, database queries, external API calls—in sequence. Combined with structured logging sinks like Elasticsearch or Application Insights, this pattern transforms debugging from guesswork into targeted investigation.

With validation, error handling, and logging established, the next challenge is efficient data access. Entity Framework Core with PostgreSQL provides the foundation, but choosing the right patterns determines whether your API stays responsive under load.

Data Access Patterns: EF Core with PostgreSQL

Entity Framework Core remains the dominant ORM for .NET applications, and for good reason. When paired with PostgreSQL, it delivers excellent performance and developer ergonomics. The challenge lies in structuring your data access layer to stay maintainable as your API grows. Getting this foundation right prevents performance bottlenecks and testing headaches down the road.

Repository Pattern: Worth the Overhead?

The repository pattern generates heated debate in the .NET community. Critics argue that EF Core’s DbContext already implements the repository and unit of work patterns, making an additional abstraction redundant. They have a point—but the abstraction provides real value in production systems.

The primary benefit isn’t abstraction for its own sake. Rather, it’s about establishing clear boundaries between your domain logic and data access concerns. When your service classes depend on IRepository<T> instead of DbContext directly, you gain flexibility to swap implementations, add caching layers, or introduce read replicas without touching business logic.

public interface IRepository<T> where T : class
{
    Task<T?> GetByIdAsync(int id, CancellationToken ct = default);
    Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default);
    IQueryable<T> Query();
    void Add(T entity);
    void Remove(T entity);
}

public class Repository<T> : IRepository<T> where T : class
{
    private readonly AppDbContext _context;
    private readonly DbSet<T> _dbSet;

    public Repository(AppDbContext context)
    {
        _context = context;
        _dbSet = context.Set<T>();
    }

    public async Task<T?> GetByIdAsync(int id, CancellationToken ct = default)
        => await _dbSet.FindAsync(new object[] { id }, ct);

    public async Task<IReadOnlyList<T>> GetAllAsync(CancellationToken ct = default)
        => await _dbSet.ToListAsync(ct);

    public IQueryable<T> Query() => _dbSet.AsQueryable();

    public void Add(T entity) => _dbSet.Add(entity);
    public void Remove(T entity) => _dbSet.Remove(entity);
}

The Query() method exposes IQueryable<T>, giving you full LINQ capabilities while keeping the abstraction thin. This pattern pays dividends when writing unit tests—mocking a simple interface beats configuring an in-memory database provider. It also makes your codebase more approachable for developers who aren’t intimately familiar with EF Core’s quirks.

Consider extending the base repository with domain-specific interfaces when queries become complex. An IOrderRepository might expose methods like GetPendingOrdersWithItemsAsync(), encapsulating include strategies and filter logic in a single, testable location.

Transaction Management Across Operations

Business operations frequently span multiple entities. The unit of work pattern coordinates these changes into a single transaction, ensuring data consistency even when multiple tables are involved.

public interface IUnitOfWork
{
    IRepository<Order> Orders { get; }
    IRepository<OrderItem> OrderItems { get; }
    IRepository<Inventory> Inventory { get; }
    Task<int> SaveChangesAsync(CancellationToken ct = default);
    Task ExecuteInTransactionAsync(Func<Task> action, CancellationToken ct = default);
}

public async Task PlaceOrderAsync(CreateOrderRequest request, CancellationToken ct)
{
    await _unitOfWork.ExecuteInTransactionAsync(async () =>
    {
        var order = new Order { CustomerId = request.CustomerId };
        _unitOfWork.Orders.Add(order);

        foreach (var item in request.Items)
        {
            var inventory = await _unitOfWork.Inventory.Query()
                .FirstAsync(i => i.ProductId == item.ProductId, ct);

            if (inventory.Quantity < item.Quantity)
                throw new InsufficientInventoryException(item.ProductId);

            inventory.Quantity -= item.Quantity;
            _unitOfWork.OrderItems.Add(new OrderItem
            {
                Order = order,
                ProductId = item.ProductId,
                Quantity = item.Quantity
            });
        }

        await _unitOfWork.SaveChangesAsync(ct);
    }, ct);
}

If any operation fails—whether from a validation exception or a database constraint violation—the entire transaction rolls back. No orphaned orders, no inventory discrepancies. This atomicity guarantee is essential for maintaining data integrity in complex business workflows.

PostgreSQL’s transaction isolation levels offer additional control. For operations requiring stronger consistency guarantees, configure the transaction with IsolationLevel.Serializable to prevent phantom reads and write skew anomalies that can occur under default isolation.

Eliminating N+1 Queries

N+1 queries silently destroy API performance. EF Core makes them easy to create and easy to miss during development when working with small datasets.

// N+1 disaster: executes 1 + N queries
var orders = await _unitOfWork.Orders.Query().ToListAsync(ct);
foreach (var order in orders)
{
    var items = order.Items; // Lazy load triggers separate query
}

// Fixed: single query with explicit include
var orders = await _unitOfWork.Orders.Query()
    .Include(o => o.Items)
    .ThenInclude(i => i.Product)
    .Where(o => o.CustomerId == customerId)
    .ToListAsync(ct);

💡 Pro Tip: Enable EF Core’s query logging during development. Add optionsBuilder.LogTo(Console.WriteLine, LogLevel.Information) to your DbContext configuration to see every SQL statement. Patterns like multiple sequential SELECTs indicate N+1 problems.

For read-heavy endpoints returning large datasets, consider projection queries that select only the fields you need. This approach reduces memory allocation and network transfer overhead significantly:

var orderSummaries = await _unitOfWork.Orders.Query()
    .Where(o => o.Status == OrderStatus.Pending)
    .Select(o => new OrderSummaryDto
    {
        Id = o.Id,
        Total = o.Items.Sum(i => i.Quantity * i.UnitPrice),
        ItemCount = o.Items.Count
    })
    .ToListAsync(ct);

This generates a single, optimized SQL query with aggregation performed at the database level—no entity materialization overhead. PostgreSQL excels at these aggregation operations, often outperforming equivalent in-memory calculations by orders of magnitude.

Split queries offer another optimization strategy for entities with multiple collection navigations. When a single query would produce a Cartesian explosion, configure EF Core with AsSplitQuery() to generate separate queries that PostgreSQL can execute efficiently.

With your data access layer structured for performance and testability, securing these endpoints becomes the next priority. Authentication and authorization in .NET extend well beyond the [Authorize] attribute.

Authentication and Authorization Beyond the Basics

Security in production APIs demands more than slapping [Authorize] on your endpoints. Enterprise applications require token refresh strategies that don’t force users to re-authenticate, granular permission models that reflect real business rules, and implementation patterns that minimize the surface area for mistakes. Getting authentication wrong means frustrated users; getting authorization wrong means data breaches. Both deserve careful attention.

JWT Authentication with Refresh Token Rotation

The standard JWT flow breaks down when you need tokens that expire quickly (for security) while maintaining seamless user sessions (for usability). Short-lived access tokens limit the damage window if a token is compromised, but forcing users to log in every fifteen minutes destroys the experience. Refresh token rotation solves this by issuing a new refresh token with each access token refresh, invalidating the previous one. If an attacker steals a refresh token, either they or the legitimate user will eventually present a revoked token—immediately signaling a breach.

public class TokenService : ITokenService
{
    private readonly JwtSettings _settings;
    private readonly IRefreshTokenStore _tokenStore;

    public async Task<TokenPair> GenerateTokenPairAsync(User user, CancellationToken ct)
    {
        var accessToken = GenerateAccessToken(user);
        var refreshToken = GenerateRefreshToken();

        await _tokenStore.StoreAsync(new RefreshTokenEntry
        {
            Token = refreshToken,
            UserId = user.Id,
            ExpiresAt = DateTime.UtcNow.AddDays(7),
            CreatedAt = DateTime.UtcNow
        }, ct);

        return new TokenPair(accessToken, refreshToken);
    }

    public async Task<TokenPair?> RotateRefreshTokenAsync(string refreshToken, CancellationToken ct)
    {
        var entry = await _tokenStore.GetAndInvalidateAsync(refreshToken, ct);
        if (entry is null || entry.ExpiresAt < DateTime.UtcNow)
            return null;

        var user = await _userRepository.GetByIdAsync(entry.UserId, ct);
        return user is null ? null : await GenerateTokenPairAsync(user, ct);
    }

    private string GenerateAccessToken(User user)
    {
        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()),
            new Claim(ClaimTypes.Email, user.Email),
            new Claim("tenant_id", user.TenantId.ToString())
        };

        var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_settings.Secret));
        var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
        var token = new JwtSecurityToken(
            issuer: _settings.Issuer,
            audience: _settings.Audience,
            claims: claims,
            expires: DateTime.UtcNow.AddMinutes(15),
            signingCredentials: credentials);

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

The GetAndInvalidateAsync method is atomic—it retrieves and deletes the token in a single operation. This prevents replay attacks where a stolen refresh token could be used multiple times before detection. Consider implementing token families: when rotation detects reuse, invalidate all tokens in that family and force re-authentication, since reuse indicates either a stolen token or a synchronization bug that warrants investigation.

Policy-Based Authorization for Complex Permissions

Role-based authorization falls apart when permissions depend on resource ownership, organizational hierarchy, or feature flags. “Can this user edit this document?” rarely has a simple yes/no answer based on roles alone. Policy-based authorization lets you express these rules declaratively, keeping authorization logic centralized while supporting arbitrarily complex business rules.

public class ResourceOwnerRequirement : IAuthorizationRequirement { }

public class ResourceOwnerHandler : AuthorizationHandler<ResourceOwnerRequirement, OwnedResource>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        ResourceOwnerRequirement requirement,
        OwnedResource resource)
    {
        var userId = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

        if (userId is not null && resource.OwnerId.ToString() == userId)
            context.Succeed(requirement);

        return Task.CompletedTask;
    }
}

Register policies that combine multiple requirements. Each requirement in a policy must succeed for the policy to pass, giving you AND logic. For OR logic, register multiple handlers for the same requirement—any handler calling Succeed satisfies that requirement.

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("CanModifyResource", policy => policy
        .RequireAuthenticatedUser()
        .AddRequirements(new ResourceOwnerRequirement()))
    .AddPolicy("TenantAdmin", policy => policy
        .RequireAuthenticatedUser()
        .RequireClaim("tenant_role", "admin", "owner"));

Minimal Boilerplate in Endpoints

Apply authorization cleanly in your endpoint definitions:

public static void MapProjectEndpoints(this RouteGroupBuilder group)
{
    group.MapPut("/{id:guid}", UpdateProject)
        .RequireAuthorization("CanModifyResource");

    group.MapDelete("/{id:guid}", DeleteProject)
        .RequireAuthorization("TenantAdmin");
}

💡 Pro Tip: Use RouteGroupBuilder to apply authorization policies to entire endpoint groups. This reduces repetition and ensures you don’t accidentally leave an endpoint unprotected.

For resource-based authorization that requires loading the resource first, inject IAuthorizationService and authorize explicitly:

static async Task<IResult> UpdateProject(
    Guid id,
    UpdateProjectRequest request,
    IProjectRepository repository,
    IAuthorizationService authService,
    ClaimsPrincipal user,
    CancellationToken ct)
{
    var project = await repository.GetByIdAsync(id, ct);
    if (project is null) return Results.NotFound();

    var authResult = await authService.AuthorizeAsync(user, project, "CanModifyResource");
    if (!authResult.Succeeded) return Results.Forbid();

    project.Update(request);
    await repository.SaveChangesAsync(ct);
    return Results.NoContent();
}

This pattern keeps authorization logic visible at the point of use while leveraging your centralized policy definitions. The explicit check also handles the common case where you need the resource loaded anyway—you avoid double-fetching while maintaining clear security boundaries.

With authentication and authorization properly implemented, you need confidence that these security boundaries hold under change. The next section covers testing strategies that verify both your business logic and your security rules.

Testing Strategies for .NET APIs

A well-architected API means nothing if you can’t deploy it with confidence. Testing .NET APIs effectively requires moving beyond unit tests that mock everything into integration tests that validate real behavior. The goal is meaningful coverage that catches actual bugs without creating a maintenance burden.

Integration Testing with WebApplicationFactory

.NET’s WebApplicationFactory creates an in-memory test server that hosts your entire application, enabling tests that exercise the full request pipeline including middleware, routing, and dependency injection. Unlike unit tests that isolate individual components, integration tests verify that your validation, serialization, authentication, and error handling work together correctly.

public class OrdersEndpointTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public OrdersEndpointTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                services.RemoveAll<DbContextOptions<AppDbContext>>();
                services.AddDbContext<AppDbContext>(options =>
                    options.UseInMemoryDatabase("TestDb"));
            });
        }).CreateClient();
    }

    [Fact]
    public async Task CreateOrder_WithValidRequest_ReturnsCreated()
    {
        var request = new CreateOrderRequest("SKU-001", 5);

        var response = await _client.PostAsJsonAsync("/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.Created);
        var order = await response.Content.ReadFromJsonAsync<OrderResponse>();
        order!.Quantity.Should().Be(5);
    }

    [Fact]
    public async Task CreateOrder_WithInvalidQuantity_ReturnsProblemDetails()
    {
        var request = new CreateOrderRequest("SKU-001", -1);

        var response = await _client.PostAsJsonAsync("/api/orders", request);

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
        var problem = await response.Content.ReadFromJsonAsync<ProblemDetails>();
        problem!.Extensions.Should().ContainKey("errors");
    }
}

The WithWebHostBuilder pattern allows you to substitute test doubles for specific services while keeping the rest of your application configuration intact. This strikes a balance between testing real behavior and controlling external dependencies like databases and third-party APIs.

Testing with Real Dependencies Using Testcontainers

In-memory databases hide bugs that only surface with real database behavior—transaction isolation levels, JSON operators, connection pooling, and constraint enforcement all behave differently. Testcontainers spins up actual PostgreSQL instances in Docker for each test run, giving you production parity without manual infrastructure setup.

public class PostgresFixture : IAsyncLifetime
{
    private readonly PostgreSqlContainer _container = new PostgreSqlBuilder()
        .WithImage("postgres:16-alpine")
        .Build();

    public string ConnectionString => _container.GetConnectionString();

    public async Task InitializeAsync() => await _container.StartAsync();
    public async Task DisposeAsync() => await _container.DisposeAsync();
}

public class OrderRepositoryTests : IClassFixture<PostgresFixture>
{
    private readonly AppDbContext _context;

    public OrderRepositoryTests(PostgresFixture fixture)
    {
        var options = new DbContextOptionsBuilder<AppDbContext>()
            .UseNpgsql(fixture.ConnectionString)
            .Options;
        _context = new AppDbContext(options);
        _context.Database.EnsureCreated();
    }
}

💡 Pro Tip: Run Testcontainers tests in parallel by giving each test class its own container instance. The startup overhead (2-3 seconds) is negligible compared to the confidence gained from testing against real PostgreSQL behavior like transaction isolation and JSON operators.

Testcontainers supports more than databases. You can spin up Redis for caching tests, RabbitMQ for messaging integration, or any containerized service your API depends on. This eliminates the “works on my machine” problem and ensures CI pipelines test against the same infrastructure as production.

Avoiding Brittle Tests

Focus tests on behavior, not implementation. Test the HTTP contract your consumers depend on rather than internal method calls. When a test breaks, it should indicate a real problem—not a refactoring that preserved behavior. Avoid asserting on exact error messages or response body structures that might change; instead, verify status codes, key fields, and business invariants.

Structure your test projects to mirror your API’s bounded contexts. Shared fixtures for expensive resources like database containers keep test suites fast while maintaining isolation through database transactions that roll back after each test. Consider using a base class that wraps each test in a transaction scope, automatically cleaning up test data without the overhead of recreating the database.

Invest in test data builders that create valid entities by default, letting individual tests override only the properties relevant to their scenario. This reduces duplication and makes tests more readable by highlighting what makes each case unique.

With reliable integration tests in place, you can deploy changes knowing they work against real infrastructure. Speaking of deployment, let’s examine how to get your tested API into production efficiently.

Deployment Considerations and Performance Tuning

A well-architected API means nothing if it falls over in production. This section covers the deployment and optimization strategies that separate hobby projects from production-grade systems.

Native AOT: Faster Starts, Smaller Footprints

.NET 8 brought Native AOT (Ahead-of-Time) compilation to production readiness for APIs. Instead of JIT compiling at runtime, your application compiles to native machine code during build time. The results are significant: cold start times drop from seconds to milliseconds, and memory footprint shrinks by 50-70%.

Native AOT works exceptionally well with Minimal APIs because they avoid the reflection-heavy patterns that cause AOT compatibility issues. If you’ve followed the architecture patterns from earlier sections—constructor injection, explicit type registration, source-generated JSON serialization—your API is already AOT-friendly.

The tradeoff is build time and binary size constraints during development. A practical approach: develop with standard JIT compilation for fast iteration, then enable AOT for production container builds. Your CI pipeline handles the longer compilation, and your production pods start in under 100ms.

Health Checks for Orchestrated Environments

Kubernetes and similar orchestrators need to know three things: Is your pod alive? Is it ready to receive traffic? Can it reach its dependencies?

.NET’s health check middleware maps directly to these concerns. Liveness probes confirm the process hasn’t deadlocked. Readiness probes verify database connections, cache availability, and downstream service reachability. Startup probes give your application time to warm up before traffic arrives.

💡 Pro Tip: Separate your health check endpoints by concern. Use /health/live for liveness (always fast, no dependencies), /health/ready for readiness (checks dependencies), and /health/startup for initial warmup verification.

Measuring What Matters

Production performance optimization starts with measurement, not assumptions. The .NET diagnostic tooling ecosystem provides everything needed: dotnet-counters for real-time metrics, dotnet-trace for detailed profiling, and dotnet-dump for memory analysis.

Focus on the metrics that impact user experience: P95 and P99 latency, not averages. A 50ms average means nothing if 5% of requests take 2 seconds. Track garbage collection frequency and duration—excessive GC pauses create latency spikes that aggregate metrics hide.

OpenTelemetry integration, which .NET supports natively, exports these metrics to your observability platform of choice. Combined with distributed tracing from your API through databases and external services, you gain visibility into exactly where time goes during request processing.

Armed with validated architecture patterns and production-hardened deployment strategies, you have the foundation for .NET APIs that scale with your organization’s needs.

Key Takeaways

• Start with Minimal APIs but establish clear boundaries using MapGroup and handler extraction before your Program.cs exceeds 100 lines
• Implement global exception handling with ProblemDetails from day one—retrofitting error handling is painful
• Use WebApplicationFactory for integration tests and treat them as your primary safety net over unit tests for API behavior