ASP.NET Core provides two approaches for building HTTP APIs:Minimal APIs and controller-based APIs.For new projects, we recommend using Minimal APIs as they provide a simplified, high-performance approach for building APIs with minimal code and configuration.

Minimal APIs - Recommended for new projects

Minimal APIs are the recommended approach for building fast HTTP APIs with ASP.NET Core. They allow you to build fully functioning REST endpoints with minimal code and configuration. Skip traditional scaffolding and avoid unnecessary controllers by fluently declaring API routes and actions.

Here's a simple example that creates an API at the root of the web app:

var app = WebApplication.Create(args);app.MapGet("/", () => "Hello World!");app.Run();

Most APIs accept parameters as part of the route:

var builder = WebApplication.CreateBuilder(args);var app = builder.Build();app.MapGet("/users/{userId}/books/{bookId}",     (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");app.Run();

Minimal APIs support the configuration and customization needed to scale to multiple APIs, handle complex routes, apply authorization rules, and control the content of API responses.

Getting started with Minimal APIs

• Tutorial:Tutorial: Create a minimal API with ASP.NET Core
• Quick reference:Minimal APIs quick reference
• Examples: For a full list of common scenarios with code examples, seeMinimal APIs quick reference

Controller-based APIs - Alternative approach

ASP.NET Core also supports a controller-based approach where controllers are classes that derive fromControllerBase. This approach follows traditional object-oriented patterns and may be preferred for:

• Large applications with complex business logic
• Teams familiar with the MVC pattern
• Applications requiring specific MVC features

Here's sample code for an API based on controllers:

namespace APIWithControllers;public class Program{    public static void Main(string[] args)    {        var builder = WebApplication.CreateBuilder(args);        builder.Services.AddControllers();        var app = builder.Build();        app.UseHttpsRedirection();        app.MapControllers();        app.Run();    }}

using Microsoft.AspNetCore.Mvc;namespace APIWithControllers.Controllers;[ApiController][Route("[controller]")]public class WeatherForecastController : ControllerBase{    private static readonly string[] Summaries = new[]    {        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"    };    private readonly ILogger<WeatherForecastController> _logger;    public WeatherForecastController(ILogger<WeatherForecastController> logger)    {        _logger = logger;    }    [HttpGet(Name = "GetWeatherForecast")]    public IEnumerable<WeatherForecast> Get()    {        return Enumerable.Range(1, 5).Select(index => new WeatherForecast        {            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),            TemperatureC = Random.Shared.Next(-20, 55),            Summary = Summaries[Random.Shared.Next(Summaries.Length)]        })        .ToArray();    }}

The following code provides the same functionality using the recommended Minimal API approach:

namespace MinimalAPI;public class Program{    public static void Main(string[] args)    {        var builder = WebApplication.CreateBuilder(args);        var app = builder.Build();        app.UseHttpsRedirection();        var summaries = new[]        {            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"        };        app.MapGet("/weatherforecast", (HttpContext httpContext) =>        {            var forecast = Enumerable.Range(1, 5).Select(index =>                new WeatherForecast                {                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),                    TemperatureC = Random.Shared.Next(-20, 55),                    Summary = summaries[Random.Shared.Next(summaries.Length)]                })                .ToArray();            return forecast;        });        app.Run();    }}

Both API projects refer to the following class:

namespace APIWithControllers;public class WeatherForecast{    public DateOnly Date { get; set; }    public int TemperatureC { get; set; }    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);    public string? Summary { get; set; }}

Choosing between approaches

Start with Minimal APIs for new projects. They offer:

• Simpler syntax - Less boilerplate code
• Better performance - Reduced overhead compared to controllers
• Easier testing - Simplified unit and integration testing
• Modern approach - Leverages the latest .NET features

Consider controller-based APIs if you need:

• Model binding extensibility (IModelBinderProvider,IModelBinder)
• Advanced validation features (IModelValidator)
• Application parts or theapplication model
• JsonPatch support
• OData support

Most of these features can be implemented in Minimal APIs with custom solutions, but controllers provide them out of the box.

See also

• Tutorial: Create a minimal API with ASP.NET Core - Minimal API tutorial
• Minimal APIs quick reference - Minimal APIs quick reference
• Create web APIs with ASP.NET Core - Controller-based APIs overview
• Tutorial: Create a controller-based web API with ASP.NET Core - Controller-based API tutorial

ASP.NET Core provides two approaches for building HTTP APIs:Minimal APIs and controller-based APIs.For new projects, we recommend using Minimal APIs as they provide a simplified, high-performance approach for building APIs with minimal code and configuration.

Minimal APIs - Recommended for new projects

Minimal APIs are the recommended approach for building fast HTTP APIs with ASP.NET Core. They allow you to build fully functioning REST endpoints with minimal code and configuration.

Here's a simple example:

var app = WebApplication.Create(args);app.MapGet("/", () => "Hello World!");app.Run();

Getting started with Minimal APIs

• Tutorial:Tutorial: Create a minimal API with ASP.NET Core
• Quick reference:Minimal APIs quick reference

Controller-based APIs - Alternative approach

Controllers are classes that derive fromControllerBase. This approach follows traditional object-oriented patterns.

Here's sample code for an API based on controllers:

namespace APIWithControllers;public class Program{    public static void Main(string[] args)    {        var builder = WebApplication.CreateBuilder(args);        builder.Services.AddControllers();        var app = builder.Build();        app.UseHttpsRedirection();        app.MapControllers();        app.Run();    }}

using Microsoft.AspNetCore.Mvc;namespace APIWithControllers.Controllers;[ApiController][Route("[controller]")]public class WeatherForecastController : ControllerBase{    private static readonly string[] Summaries = new[]    {        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"    };    private readonly ILogger<WeatherForecastController> _logger;    public WeatherForecastController(ILogger<WeatherForecastController> logger)    {        _logger = logger;    }    [HttpGet(Name = "GetWeatherForecast")]    public IEnumerable<WeatherForecast> Get()    {        return Enumerable.Range(1, 5).Select(index => new WeatherForecast        {            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),            TemperatureC = Random.Shared.Next(-20, 55),            Summary = Summaries[Random.Shared.Next(Summaries.Length)]        })        .ToArray();    }}

The following code provides the same functionality using the recommended Minimal API approach:

namespace MinimalAPI;public class Program{    public static void Main(string[] args)    {        var builder = WebApplication.CreateBuilder(args);        var app = builder.Build();        app.UseHttpsRedirection();        var summaries = new[]        {            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"        };        app.MapGet("/weatherforecast", (HttpContext httpContext) =>        {            var forecast = Enumerable.Range(1, 5).Select(index =>                new WeatherForecast                {                    Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),                    TemperatureC = Random.Shared.Next(-20, 55),                    Summary = summaries[Random.Shared.Next(summaries.Length)]                })                .ToArray();            return forecast;        });        app.Run();    }}

Both API projects refer to the following class:

namespace APIWithControllers;public class WeatherForecast{    public DateOnly Date { get; set; }    public int TemperatureC { get; set; }    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);    public string? Summary { get; set; }}

Choosing between approaches

Start with Minimal APIs for new projects. Consider controller-based APIs if you need:

• Model binding extensibility (IModelBinderProvider,IModelBinder)
• Form binding support, includingIFormFile
• Advanced validation features (IModelValidator)
• Application parts or theapplication model
• JsonPatch support
• OData support

See also

• Tutorial: Create a minimal API with ASP.NET Core - Minimal API tutorial
• Minimal APIs quick reference - Minimal APIs quick reference
• Create web APIs with ASP.NET Core - Controller-based APIs overview
• Tutorial: Create a controller-based web API with ASP.NET Core - Controller-based API tutorial