In this tutorial, you will learn how to create an ASP.NET 6 API using the new minimal API technique with C# 10. The minimal API syntax is very different compared to how developers have written C# for over 20 years. In this guide, you will learn what the minimal API syntax looks like and find out if it's coding gold, or, simply a load of old bollocks! If this sounds good to you, read on 🔥🔥🔥
As of ASP.NET 6, developers now have the ability to create an API using something called the minimal API syntax. The minimal API syntax will look strange to people who are already familiar with C#. Microsoft's aim with this new syntax is to make a C# class look more like a Node file that uses Express.js. I'm guessing the intention is to try and entice Node developers to use C#, so this raises the question, is this a feature you should use?
When you create an API using the minimal API syntax, your class will look different. You do not need namespaces or a class declaration. You do not need to inherit from a base controller. You can just write some code and jobs a good 'un, you will have an API that does something. Below shows an example of a minimal API:
At first glance, a minimal API class is different compared to the traditional way of creating a web API:
The main noticeable difference is the lack of top-level statements. The official Microsoft documentation defines top-level statements as the extra ceremony of defining the program's entry point. In ASP.NET 5 you could put the start-up code within a Main method in Progam.cs like this:
The minimal API syntax extends the removal of the top-level statement and completely removes the need for a few things within the API definition. In the new world, you will be able to define your API without the static main method, a namespace, global using statements and the API controller definition. In practical terms, we are talking about the removal of about 6 lines of code.
Personally, I do not think that it is too tall of an ask to make developers write a few lines of code. If someone comes from the Javascript world, you define classes all the time. There are also practical downsides to not using a controller for your API. The main one is less configuration. You can not decorate your minimal API code with any action filters or additional attributes. This means that if your minimal API gets more complicated, you will have to refactor your API to use a controller later. Assuming, you need to refactor at some point, using the minimal API at the start will likely mean more overall development and testing work, not less.
To create a minimal project, within Visual Studio, create a new .NET Core Web API project. On the additional information screen un-tick the Use Controller option:
Limitaions Of Minimal APIs
One of the odd things for me when creating a minimal API project is that any classes you call from your API will still need to be structured in the older syntax. This means with a minimal API, you will have classes that are not uniform in design. Personally, I prefer having a single coding standard in a project and having different classes structured in different ways makes it harder for me to review code and understand what is going on.
Another downside of not having a controller is that your program.cs will have a mix of configuration code and API logic within the same class. This will violate the single responsibility principle. I can't say that mixing these two things will increase bugs, however, the literature on the benefits of the single responsibility pattern is substantial. having different classes structured differently makes it harder for me to review code and understand what is going on.
Another downside of not having a controller is that your program.cs will have a mix of configuration code and API logic within the same class. This will violate the single responsibility principle.
Microsoft has written some good documentation on the difference between minimal API and API controllers here. To re-cap that article:
- You can not use filters with a minimal API, e.g. no action filter, authorisation, result, exception
- No model binding
- No form minding
- No model validation,
- No view rendering, e.g. Razor Pages
- No JsonPatch, OData, or ApiVersioning
This limitation changed within. .NET 7. Within .NET 7 there were a bunch of things that have improved minimal API, these include:
Now you can do everything you can in normal MVC API controllers, plus according to research made by Fasthosts, in their head-to-head survey. In terms of a minimal API vs normal API, the minimal API processed 34 thousand requests per second!
If you are stuck using .NET 6, your only option when it comes to customising how the API works is to use parameter binding (more information here). You can write code like this:
Minimal API Good Or Bad?
Personally, I struggled to see the value of minimal APIs in.NET6 . The promise of shorter syntax does not really offset the lack of capabilities and the inconsistent code structure. My opinion completely changed I'm .NET 7. NOw minimal API has like-for-like functionality and faster, its hard to argue against using it.
In terms of the original intention of maybe making something easier for Javascript developers to get started with, I personally do not feel that class structure is the most significant adoption barrier for Javascript developers. Learning to host the API is much more complicated than the Javascript equivalents. .NET hosting is also more expensive.
If you know Node and Typescript, hosting your API in Netlify takes seconds and it's free. Yes, you can get 10 free apps hosted within Azure (see this page for more information), however, in order to host your APIs you need to have a lot more knowledge of Azure compared to the Javascript equivalents. Also, what happens when you reach the 10-free limit?
An ASP.NET 6 API is faster and more suited to enterprise applications. If you were building enterprise-level APIs with it, you would use a controller, as you'd want to add caching etc.. probably using an action filter! This is why I struggle to see where minimal APIs fit in. I for one will be continuing to build things as normal!
Anyway, you do not listen to top some random dude on the internet. Do what makes you happy, happy Coding 🤘
