|
1 | 1 | --- |
2 | | -title: "APIs overview" |
3 | | -author: tdykstra |
4 | | -description: Learn about differences between controller-based APIs and minimal APIs. |
5 | | -ms.author: tdykstra |
6 | | -ms.date: 4/10/2023 |
| 2 | +title: APIs overview |
| 3 | +author: JeremyLikness |
| 4 | +description: Learn how to build fast HTTP APIs with ASP.NET Core using Minimal APIs, the recommended approach for new projects. |
| 5 | +ai-usage: ai-assisted |
| 6 | +ms.author: jeliknes |
| 7 | +ms.date: 08/15/2025 |
7 | 8 | monikerRange: '>= aspnetcore-6.0' |
8 | 9 | uid: fundamentals/apis |
9 | 10 | --- |
10 | 11 |
|
11 | | -# Choose between controller-based APIs and minimal APIs |
| 12 | +# APIs overview |
12 | 13 |
|
13 | 14 | [!INCLUDE[](~/includes/not-latest-version.md)] |
14 | 15 |
|
15 | 16 | :::moniker range=">= aspnetcore-7.0" |
16 | 17 |
|
17 | | -ASP.NET Core supports two approaches to creating APIs: a controller-based approach and minimal APIs. *Controllers* in an API project are classes that derive from <xref:Microsoft.AspNetCore.Mvc.ControllerBase>. *Minimal APIs* define endpoints with logical handlers in lambdas or methods. This article points out differences between the two approaches. |
| 18 | +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. |
18 | 19 |
|
19 | | -The design of minimal APIs hides the host class by default and focuses on configuration and extensibility via extension methods that take functions as lambda expressions. Controllers are classes that can take dependencies via constructor injection or property injection, and generally follow object-oriented patterns. Minimal APIs support dependency injection through other approaches such as accessing the service provider. |
| 20 | +## Minimal APIs - Recommended for new projects |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +Here's a simple example that creates an API at the root of the web app: |
| 25 | + |
| 26 | +```csharp |
| 27 | +var app = WebApplication.Create(args); |
| 28 | + |
| 29 | +app.MapGet("/", () => "Hello World!"); |
| 30 | + |
| 31 | +app.Run(); |
| 32 | +``` |
| 33 | + |
| 34 | +Most APIs accept parameters as part of the route: |
| 35 | + |
| 36 | +```csharp |
| 37 | +var builder = WebApplication.CreateBuilder(args); |
| 38 | + |
| 39 | +var app = builder.Build(); |
| 40 | + |
| 41 | +app.MapGet("/users/{userId}/books/{bookId}", |
| 42 | + (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}"); |
| 43 | + |
| 44 | +app.Run(); |
| 45 | +``` |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +### Getting started with Minimal APIs |
| 50 | + |
| 51 | +* **Tutorial**: <xref:tutorials/min-web-api> |
| 52 | +* **Quick reference**: <xref:fundamentals/minimal-apis> |
| 53 | +* **Examples**: For a full list of common scenarios with code examples, see <xref:fundamentals/minimal-apis> |
| 54 | + |
| 55 | +## Controller-based APIs - Alternative approach |
| 56 | + |
| 57 | +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: |
| 58 | + |
| 59 | +* Large applications with complex business logic |
| 60 | +* Teams familiar with the MVC pattern |
| 61 | +* Applications requiring specific MVC features |
20 | 62 |
|
21 | 63 | Here's sample code for an API based on controllers: |
22 | 64 |
|
23 | 65 | :::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Program.cs"::: |
24 | 66 |
|
25 | 67 | :::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Controllers/WeatherForecastController.cs"::: |
26 | 68 |
|
27 | | -The following code provides the same functionality in a minimal API project. Notice that the minimal API approach involves including the related code in lambda expressions. |
| 69 | +The following code provides the same functionality using the recommended Minimal API approach: |
28 | 70 |
|
29 | 71 | :::code language="csharp" source="~/fundamentals/apis/MinimalAPI/Program.cs"::: |
30 | 72 |
|
31 | 73 | Both API projects refer to the following class: |
32 | 74 |
|
33 | 75 | :::code language="csharp" source="~/fundamentals/apis/APIWithControllers/WeatherForecast.cs"::: |
34 | 76 |
|
35 | | -Minimal APIs have many of the same capabilities as controller-based APIs. They support the configuration and customization needed to scale to multiple APIs, handle complex routes, apply authorization rules, and control the content of API responses. There are a few capabilities available with controller-based APIs that are not yet supported or implemented by minimal APIs. These include: |
| 77 | +## Choosing between approaches |
| 78 | + |
| 79 | +**Start with Minimal APIs** for new projects. They offer: |
| 80 | + |
| 81 | +* **Simpler syntax** - Less boilerplate code |
| 82 | +* **Better performance** - Reduced overhead compared to controllers |
| 83 | +* **Easier testing** - Simplified unit and integration testing |
| 84 | +* **Modern approach** - Leverages the latest .NET features |
| 85 | + |
| 86 | +**Consider controller-based APIs** if you need: |
| 87 | + |
| 88 | +* Model binding extensibility (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinderProvider>, <xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder>) |
| 89 | +* Advanced validation features (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.Validation.IModelValidator>) |
| 90 | +* [Application parts](xref:mvc/extensibility/app-parts) or the [application model](xref:mvc/controllers/application-model) |
| 91 | +* [JsonPatch](https://www.nuget.org/packages/Microsoft.AspNetCore.JsonPatch/) support |
| 92 | +* [OData](https://www.nuget.org/packages/Microsoft.AspNetCore.OData/) support |
36 | 93 |
|
37 | | -* No built-in support for model binding (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinderProvider>, <xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder>). Support can be added with a custom binding shim. |
38 | | -* No built-in support for validation (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.Validation.IModelValidator>). |
39 | | -* No support for [application parts](xref:mvc/extensibility/app-parts) or the [application model](xref:mvc/controllers/application-model). There's no way to apply or build your own conventions. |
40 | | -* No built-in view rendering support. We recommend using [Razor Pages](xref:tutorials/razor-pages/razor-pages-start) for rendering views. |
41 | | -* No support for [JsonPatch](https://www.nuget.org/packages/Microsoft.AspNetCore.JsonPatch/) |
42 | | -* No support for [OData](https://www.nuget.org/packages/Microsoft.AspNetCore.OData/) |
| 94 | +Most of these features can be implemented in Minimal APIs with custom solutions, but controllers provide them out of the box. |
43 | 95 |
|
44 | 96 | ## See also |
45 | 97 |
|
46 | | -* <xref:web-api/index>. |
47 | | -* <xref:tutorials/first-web-api> |
48 | | -* <xref:fundamentals/minimal-apis/overview> |
49 | | -* <xref:tutorials/min-web-api> |
| 98 | +* <xref:tutorials/min-web-api> - Minimal API tutorial |
| 99 | +* <xref:fundamentals/minimal-apis> - Minimal APIs quick reference |
| 100 | +* <xref:web-api/index> - Controller-based APIs overview |
| 101 | +* <xref:tutorials/first-web-api> - Controller-based API tutorial |
50 | 102 |
|
51 | 103 | :::moniker-end |
52 | 104 |
|
53 | | -[!INCLUDE[](~/fundamentals/includes/apis6.md)] |
| 105 | +:::moniker range="= aspnetcore-6.0" |
| 106 | + |
| 107 | +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. |
| 108 | + |
| 109 | +## Minimal APIs - Recommended for new projects |
| 110 | + |
| 111 | +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. |
| 112 | + |
| 113 | +Here's a simple example: |
| 114 | + |
| 115 | +```csharp |
| 116 | +var app = WebApplication.Create(args); |
| 117 | + |
| 118 | +app.MapGet("/", () => "Hello World!"); |
| 119 | + |
| 120 | +app.Run(); |
| 121 | +``` |
| 122 | + |
| 123 | +### Getting started with Minimal APIs |
| 124 | + |
| 125 | +* **Tutorial**: <xref:tutorials/min-web-api> |
| 126 | +* **Quick reference**: <xref:fundamentals/minimal-apis> |
| 127 | + |
| 128 | +## Controller-based APIs - Alternative approach |
| 129 | + |
| 130 | +Controllers are classes that derive from <xref:Microsoft.AspNetCore.Mvc.ControllerBase>. This approach follows traditional object-oriented patterns. |
| 131 | + |
| 132 | +Here's sample code for an API based on controllers: |
| 133 | + |
| 134 | +:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Program.cs"::: |
| 135 | + |
| 136 | +:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/Controllers/WeatherForecastController.cs"::: |
| 137 | + |
| 138 | +The following code provides the same functionality using the recommended Minimal API approach: |
| 139 | + |
| 140 | +:::code language="csharp" source="~/fundamentals/apis/MinimalAPI/Program.cs"::: |
| 141 | + |
| 142 | +Both API projects refer to the following class: |
| 143 | + |
| 144 | +:::code language="csharp" source="~/fundamentals/apis/APIWithControllers/WeatherForecast.cs"::: |
| 145 | + |
| 146 | +## Choosing between approaches |
| 147 | + |
| 148 | +**Start with Minimal APIs** for new projects. Consider controller-based APIs if you need: |
| 149 | + |
| 150 | +* Model binding extensibility (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinderProvider>, <xref:Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder>) |
| 151 | +* Form binding support, including <xref:Microsoft.AspNetCore.Http.IFormFile> |
| 152 | +* Advanced validation features (<xref:Microsoft.AspNetCore.Mvc.ModelBinding.Validation.IModelValidator>) |
| 153 | +* [Application parts](xref:mvc/extensibility/app-parts) or the [application model](xref:mvc/controllers/application-model) |
| 154 | +* [JsonPatch](https://www.nuget.org/packages/Microsoft.AspNetCore.JsonPatch/) support |
| 155 | +* [OData](https://www.nuget.org/packages/Microsoft.AspNetCore.OData/) support |
| 156 | + |
| 157 | +## See also |
| 158 | + |
| 159 | +* <xref:tutorials/min-web-api> - Minimal API tutorial |
| 160 | +* <xref:fundamentals/minimal-apis> - Minimal APIs quick reference |
| 161 | +* <xref:web-api/index> - Controller-based APIs overview |
| 162 | +* <xref:tutorials/first-web-api> - Controller-based API tutorial |
| 163 | + |
| 164 | +:::moniker-end |
0 commit comments