Web API with .NET 5

Agenda: 

In this article, we will learn about RESTful WebAPI with .NET 5 (Successor of .NET Core 3.1).

1. We will create a new WebAPI project with .NET CLI in VS Code
2. We will see what’s new provided with .NET 5 WebAPI template

Tools: 

1. Visual Studio code or any IDE that supports .NET Core SDK
2. .NET 5 SDK

Description:

Step 1: At the very first, you need to install the required IDE as well the .NET 5 SDK.

Go to https://code.visualstudio.com/download and download VS Code for your operating system. I am going to use Mac for this demo.

Now, once the visual studio code is installed, go ahead and download .NET 5 SDK from https://dotnet.microsoft.com/download.

Step 2: Open Visual Studio Code and open Integrated terminal.

By default, integrated terminal opens automatically when VS Code starts, but if that doesn’t happen, follow the screenshot below.

Step 3: Before we start with the project creation, double check the version of .NET SDK installed in your machine. 

Enter the following command and hit return.

“dotnet –info”

Please check the highlighted value which makes sure that you have .NET 5 SDK installed on your machine. 

Step 4: Change the current directory of your terminal to the directory where you want to create a new project. Once you move to the desired directory, enter the following command to create a new WebAPI project.

“dotnet new webapi -o dotnet5api”

The above command will create a new webapi project with name “dotnet5api”. 

1. “webapi” is a keyword for .NET CLI to know that we want to create a project for webapi template.
2. “-o” stands for options that we want to pass to the new project creation template.
3. “dotnet5api” is the name of the project that we want to create.

Below are the files that will be generated with the new project template.

Step 5: Once the project is created, open the folder in VS code IDE.

Step 6: Once the folder is opened in VS Code, open the .csproj file and you will notice two things.

You can see that TargetFramework tag shows the framework used for the project. So, our project is .NET 5 based.

Second important thing you will notice is that a package named “Swashbuckle.AspNetCore” is installed. 

But, we didn’t installed any package in the project, right? So, where it came from?

This is a new thing that comes with .NET 5 template by default. This package is used to generate automatic documentation of your API so that it makes it easy for consumption and testing. I will show more about this later in the article.

Step 7: Now let’s look after other things in the created project. 

First we go to controllers, and you will find a controller named “WeatherForecastController”. This comes by default with the project template.

1. You will see that class name is decorated with ApiController attribute which makes this controller as REST api controller. 
2. Then you will see the route attribute and controller is mentioned in this. It tells the WebAPI host that the endpoint name will be exposed with the same name as that of controller excluding the Controller keyword from it’s name.
3. Also look at the ControllerBase Parent class. ControllerBase exposes API related features to the controller like HttpContext etc.
4. Look at the Get method, it returns a list of WeatherForecast with some data generated randomly. We create new endpoints like this as per the business needs.

Step 8: Now open Startup.cs file and focus on the highlighted code.

1. The highlighted code in ConfigureServices injects the Swagger Documentation in the request pipeline. This will generate the API documentation.
2. The highlighted code in Configure method instructs the WebAPI to generate the SwaggerUI for the developer  to test the functioning of API.

Step 9: That’s enough knowledge about the project. Now let’s run this and see what we get. 

Execute the below command to run the project.

“dotnet run”

The above screenshot states that localhost ports are active for this project. So we can head over to the mentioned URL and test the WebAPI.

Go to https://localhost:5001/swagger in your browser.

As you can see, we get a beautiful layout with the controller name and endpoints.

Expand the controller name and follow the steps mentioned in below screenshot.

The above screenshot shows the response that the API endpoint returns. 

If you see, we get the list of WeatherForecast as returned by GET method in the controller. 

You can even the Request and Response Headers. This is the beauty of the Swagger documentation.

If you hit the Request URL directly in your browser’s address bar, you will see the response data but not upto the extent which swagger exposed.

Step 10: Now as you have seen the functioning of the API, now let’s see where the ports and the configuration is defined in the project.

Go to Properties folder –> launchSettings.json. 

Look at the highlighted configuration. 

1. applicationUrl – It defines the Base URL of the API.
2. launchUrl – It defines the home page of the API which can be used as a suffix to the Base URL.

You can create as much configurations as you can which makes it really easy to expose the API.