Minimal APIs in .NET Core: Designing a Lightweight Service with Clear Boundaries

Problem Statement

Developers often need a quick HTTP endpoint for a small calculation or data lookup. Traditional ASP.NET Core templates introduce many files, middleware, and configuration, slowing iteration and increasing maintenance.

Takeaway

Minimal APIs let you define the endpoint directly in Program.cs with only a few lines, delivering a fast‑starting, low‑boilerplate service while still respecting dependency injection, validation, and operational monitoring.

Smallest Suitable Design

The minimal design consists of three concepts:

• An HTTP route defined with MapGet or MapPost.
• A service class injected via the built‑in DI container, scoped to the request.
• Automatic model binding and validation that enforce data integrity.

This design avoids separate Startup.cs or Controllers classes, keeping the codebase to a single file for small micro‑services.

Example Configuration

var builder = WebApplication.CreateBuilder(args);
// Add services with explicit lifetime if needed
builder.Services.AddScoped<ICalculator, Calculator>();
var app = builder.Build();

// Health‑check endpoint (built‑in)
app.MapGet("/health", () => "Healthy");

// Calculator endpoint
app.MapGet("/calculate/{a:double}/{b:double}", (double a, double b, ICalculator calc) => calc.Add(a, b));

app.Run();

Run the project with dotnet run from the project folder (write permission required). The route /calculate/5/7 returns 12 after model binding validates the numbers.

Trust and Data Boundaries

The built‑in DI container creates a clear trust boundary between the framework and your service code. Services are resolved per request (scoped) unless you explicitly request singleton lifetimes, preventing state leakage across requests.

Because model binding automatically validates incoming parameters (e.g., the double constraints in the route template), the service receives only data that matches the declared contract, reducing the attack surface.

Operational Checks

Minimal APIs ship with health‑check middleware and structured logging. To verify they are active:

1. Start the app.
2. Query the health endpoint with curl -s http://localhost:5000/health. A 200 response confirms the health‑check middleware is registered.
3. Inspect the console or file logs for lines indicating “Request starting” and “Request finished” around each request, confirming the middleware pipeline is executed in the expected order.

If the health check returns an error, the problem is usually missing Microsoft.AspNetCore.App metapackage or an incompatible TargetFramework.

Failure Modes

• Unhandled exceptions propagate through the pipeline and may crash the process if not caught by exception handling middleware.
• Incorrect middleware ordering can bypass validation; for example, placing app.UseAuthentication after MapGet means the endpoint runs before authentication checks.
• Version conflicts arise when multiple API projects share the same namespace and route prefixes, leading to ambiguous endpoint selection.

When Redesign Is Required

Minimal APIs are unsuited for:

• Background workers or non‑HTTP listeners (e.g., TCP sockets). In those cases, consider IHostedService or a separate worker project.
• Scenarios where implicit conventions hide configuration, such as custom routing or middleware that must run before model binding. Explicit middleware registration clarifies intent.
• Frequent breaking changes from API versioning. If you anticipate major version upgrades, adopt explicit versioned route templates (e.g., /api/v1/calculate) rather than relying on implicit conventions.

Verification Steps

1. Confirm the project file contains <TargetFramework>net6.0</TargetFramework> and references Microsoft.AspNetCore.App. This ensures the runtime provides the Minimal API APIs.
2. Execute dotnet new web-minimal -o MyService in a writable directory. Open MyService/Program.cs and verify the presence of MapGet, MapPost, and app.UseRouting() (the latter is added automatically).
3. Run dotnet build and start the app. Use curl -i http://localhost:5000/health. Expect a 200 OK with body “Healthy”.
4. Review the generated log file (or console output) for the sequence: “Application started”, “Hosting started”, then “Request starting” followed by “Request finished”. Missing steps indicate middleware ordering issues.

Conclusion

Minimal APIs give you a lean, production‑ready way to expose HTTP endpoints with minimal code while preserving clear DI boundaries, built‑in health checks, and observable logs. By defining routes directly in Program.cs, using scoped services, and verifying middleware order, you can build a trustworthy micro‑service quickly. When requirements outgrow the minimal model—such as needing background processing or complex versioning—evaluate a traditional ASP.NET Core architecture to avoid hidden technical debt. This approach balances simplicity with robustness for small services.