aspnetcore/fundamentals/apis.md
:::moniker range=">= aspnetcore-7.0"
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 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.
ASP.NET Core also supports a controller-based approach where controllers are classes that derive from xref:Microsoft.AspNetCore.Mvc.ControllerBase. This approach follows traditional object-oriented patterns and may be preferred for:
Here's sample code for an API based on controllers:
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Program.cs":::
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Controllers/WeatherForecastController.cs":::
The following code provides the same functionality using the recommended Minimal API approach:
:::code language="csharp" source="~/fundamentals/apis/MinimalAPI/Program.cs":::
Both API projects refer to the following class:
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/WeatherForecast.cs":::
Start with Minimal APIs for new projects. They offer:
Consider controller-based APIs if you need:
Most of these features can be implemented in Minimal APIs with custom solutions, but controllers provide them out of the box.
:::moniker-end
:::moniker range="= aspnetcore-6.0"
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 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();
Controllers are classes that derive from xref:Microsoft.AspNetCore.Mvc.ControllerBase. This approach follows traditional object-oriented patterns.
Here's sample code for an API based on controllers:
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Program.cs":::
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Controllers/WeatherForecastController.cs":::
The following code provides the same functionality using the recommended Minimal API approach:
:::code language="csharp" source="~/fundamentals/apis/MinimalAPI/Program.cs":::
Both API projects refer to the following class:
:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/WeatherForecast.cs":::
Start with Minimal APIs for new projects. Consider controller-based APIs if you need:
:::moniker-end