Create an web API using Asp.net core

Create ASP.NET Core Web API

Hello Everyone, In this blog we'll get to know how to create a web API using Asp.Net Core step by step using visual studio. This tutorial mainly focus on the steps how we'll create a web API using asp.net core and visual studio. Here in this tutorial we've used Visual Studio 2022. You can use any visual studio edition, the process will be the same.

In this tutorial, we'll get an overview of the steps for creating a web API. We'll not use any database to save and retrieve data in this tutorial. Those will be covered in later blogs. We'll use simple request and response to understand the process of creating a web API.

So, Let's start.

In the world of ASP.net core, there are two approaches to create a web API:-

1. Controller based APIs
2. Minimal APIs

In this tutorial, we'll proceed with traditional Web API i.e. controller based approach. It is suitable for large applications that has complex logic and handles various HTTP Requests and also document the APIs. On the other hand Minimal APIs is used where a specific feature need to handle or for smaller projects. We'll also discuss about Minimal APIs, but in the later sessions.

What is a Controller in Asp.net core web API?

Controller is a class in asp.net core web api, which handles http requests. It is responsible for processing the incoming http request and return the response. It groups set of action that can be done on a specific resource (i.e. group CRUD operation for a Entity). In web API, if we want to create, read or delete a resource, everything needs to be defined in controller. It also tells that how your web api will look like to the outer world. 

Here action belongs to controller class public methods, which will handle particular http request based on their definition inside that controller. When a client sends a http request, a corresponding Controller action method is invoked to process and return the response.

The above is the basic definition of a controller in asp.net core web api. It has lot's of features that we can implement in our web API. We'll definitely discuss them in later session. But before that we must need to know how to create a web API using controller and how it looks like.

So, lets start with steps for creating a controller based web API.

1. Open up Visual Studio. Click on Create a new project.
   
   

   

   Create a visual studio project

   
   
2. It will open up a new window, where we'll select type of project. We'll choose ASP.NET Core Web API and hit Next.
   
   

   

   Select ASP.NET Core Template for the project.

   
   
3. A new window will pop up to configure project. Please provide a Project Name which is suitable for your project. Choose location, where you want visual studio to create the project folder. Here we've named the project as EmployeeManagement because it will manages Employee details.
   
   

   

   Configure project

   
   
4. We'll also get an option to choose Framework and other details. For now we've kept them as default. Click on Create.
   
   

   

   Select the latest framework for ASP.NET Core Web API

   
   
5. This will create the project and take us to the project window. By default ASP.Net Core web API provides a default controller named as "WeatherController". You can keep that controller for learning purpose. Here We've removed the WeatherController and created a new Controller. To create a new controller, Right Click on Controllers folder and Click on Add > Controller. This will open up the following window.
   
   

   

   Removed auto generated controller.

   
   

   

   Add a new Controller.

   
   
6. Here we've chosen API > API Controller with read/write actions. This will by default generate a boilerplate code for conventional actions that will be used in that controller. If we choose API Controller - empty. It will create a empty controller and we've to manually add different types of actions that will be used inside that controller.
   
   

   

   API Controller with read/write action will generate CRUD action methods.

   
   
7. After hitting Add, it will open the window to name your controller. Conventionally, every controller class will have the suffix as Controller after it's name. So, we'll add our file name as EmployeeController.cs and it will create the controller class with the same name.
   
   

   

   Add a Controller name.

   
   
8. Here is the EmployeeController Class. As you can see, we've chosen the API Controller with read/ write action while creating the controller, that's why it has created some boilerplate action methods. Those action methods will be called by the controller based on our Http Requests.
   
   

   

   Action methods generated.

   
   

Run the project

Without Any delay let's run the project. Click on the dropdown shown below and choose https from the list. Now let's click on Run ▶.

Execute ASP.NET Core Web API Project

If you're running it for first time it will ask you to trust and install the SSL certificate for localhost. Accept that by clicking on Yes.

Trust the SSL Certificate for localhost

Install the SSL Certificate for localhost

Now, Visual Studio launches the default browser and navigates to https://localhost:<port>/swagger/index.html, where <port> is a randomly chosen port number set at the project creation.

Web API's Listed in Swagger

This is the Swagger UI, which comes by default with asp.net core web API. The main purpose of this UI is for API Testing and Documentation.

You can see five different types of APIs are created to perform operation on employee resources. Let's understand where they are coming and what is the purpose of them.

From where the APIs are coming in swagger UI

Remember while creating the controller we've selected API Controller - with read/ write actions. So, those auto generated action methods are displayed in five different APIs in swagger view. However, we can also create our own according to our requirement.

Let's understand the purpose of those action method.

Those five action methods are responsible for handling different task on a employee resources.

1. Look into the action method definition, the HttpVerb is GET and doesn't accept any parameters. That's why it will return the list of all employees.
   
   

   

   GET Employees action method.

   
   
2. Here also the HttpVerb is GET, but it accept an id as a parameter, so it will return a particular employee info based on the id.
   
   
   

   

   Get Employee By id.

   
   
3. Here the httpVerb is POST and it accepts a Request body, So as the http method POST suggest it will create a new Employee record.
   
   

   

   Create new employee.

   
   
4. Here httpVerb is PUT and it accepts id as a route parameter and a request body. So this method will be used to update praticular employee resource by an id.
   
   

   

   Update an employee record.

   
   
5. This action method clearly indicates that this will used to delete a particular employee by id.
   
   

   

   Delete employee by id.

   
   

How to decide the path of an API?

By default the path will be {http/https}://{your server url}/{Controller Name}/{action name}/{optional parameter}.

However, we can also set the custom path using Route Attribute in Controller/ Action method.

API Path

Here Controller Name = Employee

But, it is using Route Attribute in controller and inside Route the custom path is api/{Controller Name}. Also, our action method doesn't using any Route. So for the above example, the endpoint path will be 

1. api/Employee - GET 
2. api/Employee/{id} - GET 
3. api/Employee - POST
4. api/Employee/{id} - PUT
5. api/Employee/{id} - DELETE

You can verify that these APIs with the above path are generated in swagger.

Here server url is https:localhost:<port>/, where <port> is a randomly chosen port number set at the time of project creation.

Note: We'll learn about Routing in more detail in the upcoming session.

Execute a API

Now lets try to execute an API to get the response. Here we'll try with the GET api/Employee API to get the list of Employees. To execute an API expand the API in swagger and Click on Try it out. It allows us to interact with that endpoint directly from the Swagger UI. As this API doesn't require any path parameter or request body, so we can execute and get the response.

Get all employees Request example.

Get all employees response example.

Look at the response body we're getting the result which is defined in the particular action method. Also the Request URL is also same as per the discussion above.

Get all employees action method

Conclusion

This is all about creating a ASP.NET Core Web API using Controller based approach. In this tutorial, we've discussed about creating a Web API using ASP.NET core and execute the API to get a response from the API. Here, we've focused on the basics on creating a Controller and get a response. I hope now you guys will be confident in creating a web API and returning the response.

In the next tutorial, we'll discuss on CRUD (Create, Read, Update, Delete) recods into the Database using the above API. This will make you more confident on using Web API. Here is the link to CRUD using ASP.NET Core Web API and Entity Framework Core and SQL Server.

If you think this article is helpful, share with your friends. Also, If you've any doubt or have some suggestion or feedback, do share that in comments.

Thank you.

See you in the next tutorial.