dotnet / dotnet/AspNetCore.Docs

Update "Choose between Controller-based APIs and Minimal APIs" to recommend Minimal APIs

Open
#35,808 0 comments 1 reaction 1 assignee Claimed by @wadepickett View on GitHub
10.0 Pri1 seQUESTered
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.