Sponsors
- Check out this powerful framework on ABP Framework for .NET. A game-changing platform for building robust, modular, and maintainable applications faster than ever!
Controller APIs are directly connected to the way we developed our .NET applications previously, with the MVC model and Razor pages.
But hold on… we don’t use Views in APIs anymore, what we use today are tools like Swagger, Scalar, Postman or related doc tools.
Even Models or ViewModels are rarely used nowadays. Instead, we rely on something more practical and explicit: Records, DTOs and API Contracts that clearly define what goes in and out of our APIs.
But if we no longer use Views and the concept of Models, so why are we still using Controllers?
The reason is that until .NET 6, Controllers were the only fully-supported way by microsoft to build APIs in ASP.NET Core.
That made sense in the MVC world. But now, with the rise of microservices, modular APIs, and focused endpoints, does it still make sense?
Don’t get me wrong, controller APIs still have their place, but in this post, I’ll show you why Minimal APIs aren’t just a lightweight alternative, they’re a better fit for how we build APIs today.
What Are Minimal APIs?
Minimal APIs represent a significant shift in how we build HTTP APIs in .NET. Introduced officially in .NET 6, they offer a simplified and streamlined approach to defining endpoints, removing much of the ceremony traditionally required by Controllers.
At their core, Minimal APIs allow you to write HTTP endpoints with just a few lines of code, no need for Controllers, attributes, or complex routing configurations.
Here’s a simple example of a Minimal API endpoint:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello, World!");
app.Run();
Notice how this code defines a GET endpoint /hello directly, without the overhead of a Controller class or Action method, etc.
What Minimal APIs Are Not
They’re powerful, elegant, and incredibly fast to set up. But with all the excitement, some misconceptions have emerged. So before diving deeper, let’s be clear on what Minimal APIs are not:
1. Everything Lives in a Single File
Just because you can write a full API in Program.cs doesn’t mean you should.
If your Program.cs file has 500 lines of route mappings, DI registrations, and business logic…
You’re not really building a well-structured Minimal API, you’re just creating a mess in one file. Minimal APIs support modularization just like any well-designed system.
2. Just for Demos, POCs or Content creators
Yes, Minimal APIs are a fantastic choice for building quick demos, POCs, tests, or even live-coding videos. The syntax is concise, and you can get up and running in seconds.
But don’t mistake their simplicity for limitation. Minimal APIs are absolutely production-ready and scalable.
You can handle versioning, authentication, validation, and more, the key is knowing how to structure them well.
3. A Replacement for Controllers
One common narrative is: “Minimal APIs are here to replace Controllers.” But that’s not the full story.
While it’s true that many developers are moving away from controllers, that doesn’t mean they’re obsolete. Controllers still power the majority of .NET APIs today and are well-supported. Minimal APIs are an alternative, not a replacement, especially for smaller, focused endpoints or microservices.
And let’s not forget: Minimal APIs are still evolving. The upcoming support for validation filters, no .csproj file. in .NET 10 and .NET 9 the performance improvements is a great example of how is still expanding. There’s a lot of potential, but it’s still catching up in some areas. That’s important to keep in mind.
4. A Lazy Way to Build APIs
If you think Minimal APIs are just a “lazy” way to skip boilerplate, think again.
The fact that they look simpler doesn’t mean they’re “less professional.” Minimal APIs can be just as good as controllers when implemented correctly. You still need good practices: validation, testing, error handling, separation of concerns, and so on.
Don’t confuse minimal syntax with minimal design. It’s about eliminating friction, not cutting corners.
How I Structure My Minimal API Projects (Folder by Folder)
A well-defined project structure is essential to ensure maintainability and scalability, especially in larger projects. Here’s how I typically organize my Minimal API projects to keep everything clean, cohesive, and easy to navigate:
📁 Notes.Api
├── 📁 Contracts
├── 📁 Database
├── 📁 Domain
├── 📁 Endpoints
│ ├── 📁 Notes
│ │ ├── CreateNoteEndpoint.cs
│ │ ├── DeleteNoteEndpoint.cs
│ │ └── GetAllNotesEndpoint.cs
│ └── NoteEndpoints.cs // (optional) just NotesEndpoints.cs
├── 📁 Mapping
├── 📁 Migrations
├── 📁 Services
└── 📁 Validation
└── CreateNoteRequestValidator.cs
This approach certainly streamlines our Minimal API definitions, and it’s great how it lets us group endpoints by feature in one centralized spot. I believe this significantly boosts the maintainability of Minimal APIs and then remembering to invoke those extensions within Program.cs.
Example using NoteEndpoints.cs:
public static class NoteEndpoints
{
public static void MapNoteEndpoints(this IEndpointRouteBuilder app)
{
app.MapGet("notes", async (
INoteService noteService,
CancellationToken ct,
int page = 1,
int pageSize = 10) =>
{
// ...
});
app.MapGet("notes/{id:int}", async (
int id,
INoteService noteService,
CancellationToken ct) =>
{
// ...
});
app.MapDelete("notes/{id:int}", async (
int id,
INoteService noteService,
ILogger<Program> logger,
CancellationToken ct) =>
{
// ...
});
}
}
And then inside of Program.cs we need to register the endpoints:
app.MapNoteEndpoints();
Example using CreateNoteEndpoint.cs:
[HttpPost("notes"), AllowAnonymous]
public class CreateNoteEndpoint: Endpoint<CreateNoteRequest, NoteResponse>
{
private readonly INoteService _noteService;
public CreateNoteEndpoint(INoteService noteService)
{
_noteService = noteService;
}
public override async Task HandleAsync(CreateNoteRequest request, CancellationToken ct)
{
// ...
}
}
This pattern, sometimes referred to as the REPR (Request-Endpoint-Response) pattern or a form of Vertical Slice Architecture makes dependency injection straightforward and keeps each endpoint’s concerns isolated.
When Should You Use Minimal APIs in .NET?
They strip away ceremony and let you focus on what matters:
Perfect Use Cases
Proofs of Concept (POCs): You need to validate an idea fast. No time to wire up controllers, services, or boilerplate. Minimal APIs get you from 0 to a working endpoint in seconds.
Demos and tutorials: Teaching a concept or showcasing a feature? Minimal APIs keep the focus on what you’re demonstrating, not the infrastructure around it.
Developer content creation: Blog posts, GitHub examples, YouTube walkthroughs, clarity matters. Minimal APIs help you write expressive and concise examples.
Microservices: Minimal APIs are ideal here. Microservices should be small, focused, and fast. The lower startup overhead and cleaner request pipeline are perfect for this architecture.
See the performance graphs and comparison with other languages using minimal APIs:
Minimal APIs in .NET 9 bring significant improvements, handling 15% more requests per second than .NET 8. Additionally, they use 93% less memory, making your applications faster and more efficient, and its 10x faster than Node.js and 5x faster than go.
While Minimal APIs shine in simplicity and speed, they can become less effective as your application grows in size and complexity. Large monolithic systems and modular monoliths demand well-defined boundaries, layered responsibilities, and orchestration mechanisms, needs that can quickly outgrow the flat structure Minimal APIs encourage.
Conclusion
By stripping away unnecessary boilerplate, Minimal API let developers focus on what truly matters: clear, maintainable, and high-performance endpoints. As we’ve seen, Minimal APIs enable a modular, scalable approach that fits perfectly with the demands of modern microservices and serverless architectures.
However, this simplicity doesn’t mean you should throw away good practices. Clean separation of concerns, proper validation, dependency injection, and robust error handling remain critical. The real power of Minimal APIs comes when you combine their lightweight syntax with well-structured project organization, such as grouping endpoints by feature and embracing patterns like REPR or Vertical Slice, which enhance maintainability without sacrificing clarity.
So, why are so many .NET developers saying goodbye to controllers? Because Minimal APIs align better with today’s development needs, faster startup, less overhead, easier to read, and a more explicit contract for what your API does. Whether you’re building a microservice, a quick POC, or a production-ready API, Minimal APIs deserve a serious look in your toolbox.
Are you ready to leave the heavy controllers behind and embrace the streamlined future of .NET API development?
Thank you for reading.
See you next time!
Sponsors
- Check out this powerful framework on ABP Framework for .NET. A game-changing platform for building robust, modular, and maintainable applications faster than ever!
