dotnet / dotnet/AspNetCore.Docs
Update "Choose between Controller-based APIs and Minimal APIs" to recommend Minimal APIs
- Dominant language
- C#
- Stars
- 13.1k
- Forks
- 24.6k
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 109
Description
[EDIT by guardrex to add the metadata. Recommend opening from the bottom of the article to get the metadata and author ping.]
# Issue description
The [Choose between Controller-based APIs and Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/apis?view=aspnetcore-10.0) article should updated to recommend Minimal APIs over Controller-based API apps.
# Software versions
Check the .NET target framework(s) being used, and include the version number(s).
* [x] .NET Core 10.0 and later
* [ ] .NET 5.0 or later
* [ ] .NET Framework
* [ ] .NET Standard
----
#### Additional Instructions from @wadepickett for an plan to resolve this issue
The following instructions build upon the original issue and are meant to provide more specific guidance for implementation
[aspnetcore/fundamentals/apis.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/apis.md) already recommends Minimal APIs for new projects. Below are additional steps to be taken to strengthen the recommendation for Minimal APIs **specifically for ASP.NET Core 10.0 and later versions only**:
1. **Update introduction paragraphs**:
- Replace "For new projects, we recommend using Minimal APIs" with "**Minimal APIs are the recommended approach for building HTTP APIs**"
2. **Modify section headings**:
- Change "Minimal APIs - Recommended for new projects" to "Minimal APIs - Recommended approach"
3. **Enhance Minimal APIs descriptions**:
- Add more compelling descriptions of benefits in the introduction
- Include advantages like: streamlined experience, less boilerplate, better performance
4. **Reposition Controller-based APIs section**:
- Present it as an "Alternative approach" rather than an equal option
- Begin the section with "While Minimal APIs are recommended..."
5. **Strengthen recommendation language**:
- In the "Choosing between approaches" section, change to "Start with Minimal APIs for most projects"
- Use "Consider controller-based APIs only if you specifically need" before listing specialized features
6. **Apply only to ASP.NET Core 10.0+**:
- Make these changes only to the moniker range for ASP.NET Core 10.0+
- Do not modify content for earlier versions
---
#### Document Details
⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*
* ID: 4841921d-fe70-1264-88ff-b2f2d067b212
* Version Independent ID: 4841921d-fe70-1264-88ff-b2f2d067b212
* Platform ID: e6e75157-5131-382b-4f17-f6060e78122c
* Content: [APIs overview](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/apis?view=aspnetcore-10.0)
* Content Source: [aspnetcore/fundamentals/apis.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/apis.md)
* Service: **aspnet-core**
* Sub-service: **fundamentals**
* GitHub Login: @tdykstra
* Microsoft Alias: **tdykstra**
---
[Associated WorkItem - 484452](https://dev.azure.com/msft-skilling/Content/_workitems/edit/484452)
Contributor guide
Assessment
This issue has not been assessed yet.