What Is a Minimal API in ASP.NET Core?

What Is a Minimal API?

A Minimal API is a simple way to build HTTP APIs with ASP.NET Core. It lets you define routes and handlers with little setup. Most endpoint code can live in Program.cs, without controller classes.

Microsoft introduced Minimal APIs in .NET 6. The model has grown since then. .NET 10 adds more mature support for validation, typed results, and OpenAPI workflows. You can now build small services without giving up key ASP.NET Core features.

Instead of mapping a route to a controller action, you map it to a delegate. That delegate reads input, runs business logic, and returns a result. This makes the request flow easy to see.

Minimal APIs work well for small HTTP services, internal tools, and microservices. They also suit serverless apps, where a small startup cost can matter.

Why Developers Choose Minimal APIs

The main Minimal API advantage is less boilerplate. You do not need a controller, action method, and several setup files for every small feature. Fewer files can make a focused service easier to scan and change.

Less ceremony can also reduce startup work. The app has fewer layers to build and inspect. Performance still depends on your database, network, and code. Yet a lean endpoint gives you a strong base.

Minimal APIs also keep related code close together. A route, its input type, and its response can sit in one small area. This helps when you build a simple CRUD service with only a few resources.

They still support dependency injection, filters, authentication, authorization, and middleware. You can add structure as the app grows. Start small, then split code into route groups or separate files when needed.

• Less code for common endpoints
• Clear route-to-handler flow
• Strong support for typed responses
• Built-in OpenAPI document generation
• A good fit for small services and microservices

Setting Up a Minimal API Project

Creating a Minimal API project starts with the .NET command line tool. Install the .NET SDK first. Then run these commands in a terminal:

dotnet new web -n ProductApi
cd ProductApi
dotnet run

The web template creates a small ASP.NET Core app. Its main file is Program.cs. The generated app includes a web host and a basic pipeline.

Open Program.cs and add a route. The following example returns a plain string:

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

app.MapGet("/", () => "Product API is running");

app.Run();

Run the app, then request the root path in a browser or API tool. The handler runs when the request uses GET. For a real service, you would return data from a store instead.

For a fuller setup, add services before builder.Build(). This is where you register a database context, application services, or OpenAPI support. Keep startup code short by moving larger handlers into other files.

Defining Routes and HTTP Handlers

A route handler is the code that responds to a matched request. Each HTTP method has a matching map method. Common choices include MapGet, MapPost, MapPut, and MapDelete.

Here is a small product set. It shows common CRUD operations:

app.MapGet("/products", () => products);
app.MapGet("/products/{id}", (int id) => FindProduct(id));
app.MapPost("/products", (Product product) => AddProduct(product));
app.MapPut("/products/{id}", (int id, Product product) => UpdateProduct(id, product));
app.MapDelete("/products/{id}", (int id) => RemoveProduct(id));

The route pattern controls which requests reach each handler. The {id} part marks a value from the URL. The handler can then use that value to find one product.

For larger apps, group related routes with MapGroup. A group can share a path prefix and common rules. This keeps a large set of endpoints tidy.

Method	Typical use	Example route
GET	Read data	/products
POST	Create data	/products
PUT	Replace or update data	/products/7
DELETE	Remove data	/products/7

Automatic Parameter Binding

Minimal APIs bind handler parameters from the request for you. A simple type can come from the route, query string, or headers. A complex type can come from the request body.

For example, this handler reads an ID from the route and a filter from the query string:

app.MapGet("/products/{id}", (int id, string? filter) =>
{
 return Results.Ok(new { id, filter });
});

The framework sees id in the route. It looks for filter in the query string. You do not need an attribute for either value.

Body binding works in much the same way. A product parameter tells ASP.NET Core to read JSON from the request body. The framework then turns that JSON into a Product object.

Use explicit binding attributes when a source needs to be clear. Attributes such as [FromHeader] and [FromBody] can remove doubt. Most simple handlers need no extra markup.

Validating Input Data

Validation checks input before your app saves or uses it. Data Annotations offer a simple model for common rules. You can mark fields as required, set length limits, or check numeric ranges.

public sealed class Product
{
 public int Id { get; set; }

 [Required]
 [StringLength(80)]
 public string Name { get; set; } = "";

 [Range(0.01, 100000)]
 public decimal Price { get; set; }
}

In newer ASP.NET Core versions, Minimal APIs can use built-in validation support. Invalid input can produce a client error before the handler does its main work. This helps protect your data layer.

Validation rules should match real business needs. A required name may be enough for one service. Another may need rules for stock levels, currency, or allowed status values.

Return clear errors when a request fails. Clients need to know which field needs a fix. Do not trust client checks alone. The server must check every request.

Using TypedResults and OpenAPI

TypedResults give handlers a known response type. They make the result shape clearer to both readers and tools. They also help OpenAPI describe possible responses.

app.MapGet("/products/{id}", Results<Ok<Product>, NotFound> (int id) =>
{
 var product = FindProduct(id);
 return product is null
 ? TypedResults.NotFound()
 : TypedResults.Ok(product);
});

This handler can return either a product or a not-found response. The type makes that choice visible in the method signature. It also reduces guesswork during client generation.

OpenAPI creates a machine-readable description of your API. Tools can use it to build test pages and client code. ASP.NET Core supports automatic document generation through its OpenAPI tools.

Microsoft's Minimal API OpenAPI guidance covers document setup and endpoint metadata. Add a document service before building the app, then map the document endpoint as needed.

For a new service, define the contract early. Name routes clearly. Choose response codes with care. Good types and docs make your API easier to use.

When Should You Use a Minimal API?

Minimal APIs suit services with a clear and limited scope. They are useful for health checks, webhooks, small CRUD systems, and edge functions. They can also support larger apps when you add route groups and good file structure.

Controllers may fit better when a team needs a strict pattern across many features. They can also help when an app has complex filters, shared action logic, or long-lived MVC code. Both styles use the same ASP.NET Core platform.

Choose based on the shape of the service. Do not choose by line count alone. A small route set often benefits from Minimal APIs. A large domain may need stronger boundaries around each feature.

The best starting point is a small endpoint. Add typed results, validation, and OpenAPI support from the start. That gives you a lean app with room to grow.