Building HTTP Endpoints with C# Minimal APIs

Minimal APIs, introduced in .NET 6, provide an architecturally streamlined approach to building lightweight HTTP services with C#. This article explores what Minimal APIs are, how they remove traditional boilerplate code, their core mechanics for routing and dependency injection, and why they serve as a modern alternative to traditional controller-based Web APIs.

What Are Minimal APIs?

Minimal APIs are an alternative to the traditional Model-View-Controller (MVC) pattern in ASP.NET Core. Rather than requiring developers to scaffold controllers, define action filters, and manage extensive project structures, Minimal APIs allow developers to declare HTTP endpoints directly in the Program.cs file using lambda expressions or methods.

This architectural shift focuses on simplicity and high performance, making .NET competitive with lightweight web frameworks in other languages, such as Express.js in Node.js or Flask in Python.

How Minimal APIs Simplify Development

1. Elimination of Boilerplate Code

In a traditional ASP.NET Core Web API, exposing a single endpoint typically requires:

  • A Startup.cs or complex Program.cs configuration.
  • A dedicated controller class inheriting from ControllerBase.
  • Specific attributes such as [ApiController], [Route], and [HttpGet].

Minimal APIs collapse this structure into just a few lines of code:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () => "Hello, World!");

app.Run();

By removing the ceremony of classes and namespace declarations, developers can focus directly on application logic.

2. Direct Route Mapping

Minimal APIs provide fluent extension methods on the WebApplication instance to handle HTTP verbs directly:

  • app.MapGet(pattern, handler)
  • app.MapPost(pattern, handler)
  • app.MapPut(pattern, handler)
  • app.MapDelete(pattern, handler)

These methods bind directly to endpoint routes, reducing the indirection caused by attribute routing spread across multiple controller files.

3. Automatic Parameter Binding

ASP.NET Core's parameter binding engine works seamlessly with Minimal APIs. The framework automatically resolves parameters defined in the endpoint handler based on their source:

  • Route parameters: Extracted from matching route tokens (e.g., /users/{id}).
  • Query strings: Matched against standard data types if not found in the route.
  • Request bodies: Complex objects are automatically deserialized from JSON.
  • Dependency Injection services: Registered services are automatically injected into the lambda arguments without explicit attribute declarations.
app.MapPost("/users", (User user, IUserService userService) => 
{
    var createdUser = userService.Create(user);
    return Results.Created($"/users/{createdUser.Id}", createdUser);
});

4. Grouping and Organization

To prevent Program.cs from becoming cluttered as an application grows, Minimal APIs include the MapGroup extension. Route groups allow developers to prefix routes, apply common authorization rules, and attach metadata to a collection of endpoints in one location:

var users = app.MapGroup("/users").RequireAuthorization();

users.MapGet("/", GetAllUsers);
users.MapGet("/{id}", GetUserById);

Endpoints can also be organized into separate extension methods or static classes to maintain a clean architecture.

5. Superior Performance and Reduced Startup Time

Minimal APIs bypass the reflection-heavy controller discovery process used by the MVC framework during application startup. Because the framework does not need to scan assemblies for controller types and actions, Minimal APIs feature lower memory overhead and significantly faster cold-start times. This makes them ideal for microservices, containerized workloads, and cloud-native serverless environments like AWS Lambda or Azure Functions.

When to Use Minimal APIs

Minimal APIs are best suited for:

  • Microservices and Cloud Functions: Where rapid startup times and minimal resource usage are essential.
  • Simple REST Endpoints: When building CRUD operations that do not require complex view logic.
  • Prototyping: Allowing rapid iterations without unnecessary file scaffolding.

While controller-based APIs remain fully supported for large, legacy enterprise systems requiring complex action filters or deep MVC features, Minimal APIs have become the standard recommendation for modern HTTP endpoint development in .NET.