A Guide to .NET Minimal APIs

With the release of .NET 6, Microsoft introduced a new, streamlined way to build web APIs: Minimal APIs. This feature is designed to reduce the ceremony and boilerplate traditionally associated with creating simple HTTP APIs in ASP.NET Core, allowing you to build a fully functional API in just a few lines of code.

It's a fantastic entry point for developers new to .NET and a highly productive choice for building microservices and small-scale APIs.

The Old Way: Controller-Based APIs

Before .NET 6, if you wanted to create a web API, you would use the MVC pattern with controllers. This involved creating a Startup.cs file for configuration, a Program.cs file to set up the host, and a separate controller class for your endpoints.

While this is a powerful and scalable pattern, it involves a lot of files and boilerplate code for simple scenarios.

The New Way: Minimal APIs

Minimal APIs leverage C# 9's top-level statements and new routing extensions to let you define your entire API in a single Program.cs file.

Here's a complete, runnable web API in .NET 6:

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

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

app.Run();

That's it! This code creates a web server and defines a single endpoint that responds to GET requests at the root URL with the text "Hello, World!".

How It Works

1. WebApplication.CreateBuilder(args): This creates a web application builder with a default configuration.
2. var app = builder.Build(): This builds the WebApplication instance.
3. app.MapGet("/", ...): This is where you define your endpoints. You map a URL pattern and an HTTP method (like MapGet, MapPost, MapPut, MapDelete) to a handler function. The handler is typically a lambda expression.
4. app.Run(): This starts the web server and begins listening for requests.

Dependency Injection and More

Minimal APIs are simple, but they are not simplistic. They have full support for the powerful features of ASP.NET Core, including dependency injection.

You can register your services with the builder and then have them injected directly into your route handlers.

// Register a service
builder.Services.AddScoped<MyService>();

var app = builder.Build();

// Inject the service into the handler
app.MapGet("/hello/{name}", (string name, MyService service) => 
{
    return service.GetGreeting(name);
});

Minimal APIs vs. Controllers

So, should you stop using controllers? Not necessarily. The two approaches can coexist, and the right choice depends on your scenario.

• Use Minimal APIs when:

  • You are building a small microservice with only a few endpoints.
  • You want to get started quickly with minimal boilerplate.
  • You are teaching or learning ASP.NET Core.

• Use Controllers when:

  • You are building a large, complex API with many endpoints.
  • You need the rich feature set that comes with controllers, such as model binding from forms, views, or complex filtering logic that can be shared across many actions.
  • You prefer the structure and organization that comes from separating your endpoints into different controller classes.

You can even mix and match both styles in the same application.

Conclusion

Minimal APIs are a fantastic addition to the ASP.NET Core framework. They provide a simple, elegant, and highly productive way to build lightweight web APIs. By reducing the amount of ceremony required to get started, they make .NET a more attractive and accessible platform for a whole new range of applications and developers, without sacrificing the power and performance that ASP.NET Core is known for.