Building Lightweight Services with ASP.NET Core Minimal APIs

Problem: Too Much Ceremony for Simple Services

When you need a tiny HTTP endpoint — perhaps a health check, a webhook receiver, or a prototype API — creating a full MVC controller with its own class file, routing attributes, and a Startup/Program.cs setup can feel like overkill. The extra files add mental overhead and slow down iteration, especially in microservice‑oriented projects where many services are small and focused.

Thesis: Minimal APIs give you the power of ASP.NET Core without the boilerplate

ASP.NET Core Minimal APIs let you define route handlers directly in a single file using top‑level statements. You still get the built‑in dependency injection (DI) container, routing, model binding, validation, and content negotiation, but you eliminate the separate Startup class and controller classes. This approach is ideal for lightweight services while preserving the ability to add custom middleware or host‑builder configuration when the project grows.

How Minimal APIs Work

The WebApplicationBuilder created by WebApplication.CreateBuilder(args) configures the host, services, and logging just like the traditional Startup class. After building the app with builder.Build(), you register endpoints using methods on the returned WebApplication instance — for example, app.MapGet, app.MapPost, etc. Lambda expressions or local functions can receive injected services directly from the DI container, so you write something like app.MapGet("/hello", (IMyService svc) => svc.GetMessage());.

Worked Example: Hello Service with DI

1. Create a new web project (run in a folder where you have write permission):

   dotnet new web -n MinimalApiDemo
   cd MinimalApiDemo
   

   The dotnet new web template produces a Program.cs with a basic minimal API.

2. Define a simple service that will be injected into the handler. Replace the contents of Program.cs with the following code:

   using Microsoft.AspNetCore.Builder;
   using Microsoft.Extensions.DependencyInjection;
   using Microsoft.Extensions.Hosting;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Register a scoped service
   builder.Services.AddScoped();
   
   var app = builder.Build();
   
   app.MapGet("/hello", (IMessageService svc) =>
       Results.Ok(new { Message = svc.GetMessage() }));
   
   app.Run();
   
   public interface IMessageService
   {
       string GetMessage();
   }
   
   public class MessageService : IMessageService
   {
       public string GetMessage() => "Hello from a Minimal API!";
   }
   

   This file uses top‑level statements, registers IMessageService as a scoped service, and maps a GET endpoint that returns JSON.

3. Run the service and verify the response:

   dotnet run
   

   The command prints the listening URLs, typically something like http://localhost:5000 and https://localhost:7001. Open a browser or use curl to call the endpoint:

   curl http://localhost:5000/hello
   

   You should see a JSON payload similar to:

   { "message": "Hello from a Minimal API!" }
   

   If another process is already using port 5000, the SDK will choose a different port and display it in the console; adjust the URL accordingly.

4. Practical check: confirm DI works by changing the implementation of MessageService.GetMessage to return a timestamp and re‑running dotnet run. The updated value appears in the response without recompiling a separate controller class.

Trade‑off and Limitations

Minimal APIs excel at simplicity, but they are not a drop‑in replacement for every scenario:

• Features that rely heavily on controller conventions — such as Razor view rendering, OData endpoints, or advanced API versioning — are either unavailable or require extra work.

• Debugging inline lambdas can be harder because the handler code lives inside the Program.cs file; stepping into a lambda may show less clear call stacks compared with a dedicated controller class.

• As the number of endpoints grows, a single file can become unwieldy. At that point, splitting handlers into separate classes (still using minimal API routing) or migrating to traditional controllers improves maintainability.

These limitations do not disqualify Minimal APIs for many microservices, internal tooling, or prototypes; they simply mean you should evaluate whether the reduced ceremony outweighs the need for advanced controller‑specific features.

Actionable Closing

If you are building a service that primarily exchanges JSON data and does not require server‑side views or complex versioning, start with a Minimal API. It gives you immediate access to ASP.NET Core’s robust DI, routing, and middleware pipeline while keeping the project footprint small. As the service evolves, you can extract handlers into separate classes or move to a controller‑based architecture without rewriting the core logic. Begin by running the commands above, inspect the JSON output, and decide whether the lightweight approach fits your current engineering decision.