Introduction to ASP.NET Web API

Back to: ASP.NET Web API Tutorials For Beginners and Professionals

Introduction to ASP.NET Web API:

In this article, I am going to give you a brief introduction to ASP.NET WEB API Framework. At the end of this article, you will have a very good understanding of the following things

Let’s discuss each of these questions one by one.

What is ASP.NET Web API?

The term API stands for “Application Programming Interface”. ASP.NET Web API is a framework, provided by Microsoft, which makes it easy to build Web APIs, i.e. HTTP based services. The ASP.NET Web API is an ideal platform for building Restful services on top of the .NET Framework. These Web API services can be consumed by a variety of clients such as

1. Browsers
2. Mobile applications
3. Desktop applications
4. IOTs, etc.

The most important thing to keep in mind is that we can develop both Restful and Non-Restful Web Services using the ASP.NET Web API framework. But mostly this framework is used to create RESTful services. In short, this framework does not provide any specific architectural style for creating the services. In this article series, we are going to discuss creating RESTful services from scratch using the Web API framework.

What are IOTs?

IOTs stands for Internet Of Things and it is actually a network of physical devices, buildings,  vehicles, and other items that are embedded with electronics, sensors, software, actuators, and network connectivity that enable these objects to collect and exchange information or you can say data.

In other words, we can say, the Internet Of Things (IoT) are the objects or devices which should have an IP address and they can communicate with other Internet-enabled devices and objects over the Internet. Examples of IoT include security systems, thermostats, electronic appliances, cars, etc, in addition to laptops, desktops, and smartphones.

What is Rest?

REST stands for Representational State Transfer. This is an architectural pattern used for exchanging data over a distributed environment. In Rest, there is something called Client and Server, and the data can be exchanged between the client and server over a distributed environment. Distributed environment means the client can be on any platform like Java, .NET, PHP, etc. and the server can also be on any platform like Java, .NET, PHP, etc. The REST architectural pattern treats each service as a resource and a client can access those resources by using HTTP Protocol methods such as GET, POST, PUT, PATCH, and DELETE.

What are HTTP Verbs or HTTP Methods?

In Restful services, the HTTP Verbs identify what type of operation, the service is going to be performed. Let us understand what all HTTP Methods or Verbs are available.

GET Method:

The GET HTTP Method is used to Retrieve the Data. The HTTP GET method requests a representation of the specified resource. Requests using GET should only be used to request data (they shouldn’t include data). For example, you want to search something like you want to get the list of employees, list of products, you want to retrieve a book by id, etc. So, whenever you are expecting some data from the server, you need to use GET HTTP Verb.

In the case of the HTTP Get Method, the Web API may be expecting some data from the client, but the main purpose of the GET method is to fetch or retrieve data from the server. If you want to implement some kind of search functionality then the Web API may expect some data to filter out the results. In this case, the clients need to send the data.

POST Method:

The POST request is used to make a new entry in the database. It is not only specific to a database, whenever you want to create a new resource in your application, then you need to use the POST method.

What does it mean by adding a new Resource? It means if you want to add a new Employee, or you want to add a new product. So, here the main concept is not the database, the main concept is adding a new resource.

PUT Method:

PUT is also one of the HTTP Verb. The PUT method is used to update all the properties of the current resource in the database. What does it mean? For Example, we have a table called Product in our database. If we want to update all properties of a particular product (i.e. current resource) then we need to use PUT HTTP Request. So, whenever you want to update all the properties (column) of a resource (existing record in the database), then you need to use PUT Method. You cannot add a new resource using the PUT method.

PATCH Method:

There are some situations where you don’t want to update all the properties of an existing resource instead you want to update a few of the properties, then you need to use the PATCH method. So, the PATCH method is similar to the PUT method, but it is used to update a few properties of the current resource in the database. For example, if you want to update a few properties (columns) of an existing product then you need to use the PATCH method. That means if your Product table contains 10 columns, and you want to update only four columns of an existing product, then you need to use the PATCH method.

DELETE Method:

The DELETE method is used to delete the resource from the database. That means you are removing or deleting an existing entity from your database. In modern applications, we use two concepts for delete. One is Soft Delete and another one is Hard Delete.

1. Soft Delete: In your table, if you have some column like IsDeleted or IsActive, or something similar to this and you just want to update that column, then you cannot use Delete Method. In that case, you need to use the PATCH method. This is because you are not deleting the record from the database, you just update the record.
2. Hard Delete: If you want to remove the existing entity from the table, then you need to use the DELETE method. For example, Delete an existing product from the Product table in the database, etc.

There are other HTTP Methods available, but these are the most used HTTP Methods, we generally used in our applications.

What are the RESTful services?

REST stands for Representational State Transfer. REST is an architectural pattern used for exchanging data over a distributed environment. REST architectural pattern treats each service as a resource and a client can access these resources by using HTTP protocol methods such as GET, POST, PUT, PATCH, and DELETE. The REST architectural pattern specifies a set of constraints that a system should be adhered to. Here are the REST constraints.

1. Client-Server Constraint:

This is the first constraint. This constraint specifies that a Client sends a request to the server and the server sends a response back to the client. This separation of concerns supports the independent development of both client-side and server-side logic. That means client applications and server applications should be developed separately without any dependency on each other. A client should only know resource URIs and that’s all. 

2. Stateless Constraint:

The next constraint is the Stateless Constraint. The stateless constraint specifies that the communication between the client and the server must be stateless between requests. That means the server should not be storing anything on the server related to the client. The request from the client should contain all the necessary information so that the server can identify the client and can process that request. This ensures that each request can be treated independently by the server.

3. Cacheable Constraint:

In real-time applications, some data provided by the server is not changed that frequently like the list of Countries, the list of States,  the list of cities, and some master data. The Cacheable Constraint says that let the client know how long this data is good for so that the client does not have to come back to the server for that data over and over again.

4. Uniform Interface Constraint:

The Uniform Interface Constraint defines an interface between the client and the server. To understand the uniform interface constraint, first, we need to understand what a resource is and the HTTP verbs such as GET, PUT, POST, PATCH, and DELETE. In the context of a RESTFUL Service, resources typically represent data entities. The Product, Employee, Customer, Country, State, City, etc. are all resources. The HTTP verb (GET, PUT, POST, PATCH, and DELETE) that is sent with each request tells the API what to do with the resource. Each resource is identified by a specific URI (Uniform Resource Identifier).

5. Content Negotiation:

One of the constraints of the REST service is that the client should have the ability to decide in which format they want the response – whether they want the response in XML or JSON etc. This is called Content Negotiation

6. Layered System:

REST allows us to use a layered system architecture where we deploy the APIs in server A, and store data on server B and authenticate requests in server C. For example, a client cannot ordinarily tell whether it is connected directly to the server or to an intermediary along the way.

What is the difference between REST and SOAP?

Let us discuss the difference between the REST and SOAP service:

1. SOAP stands for Simple Object Access Protocol whereas REST stands for Representational State Transfer.
2. The SOAP is an XML-based protocol whereas REST is not a protocol rather it is an architectural pattern i.e. resource-based architecture.                         
3. SOAP has specifications for both stateless and state-full implementation whereas REST is completely stateless.
4. SOAP enforces message format as XML whereas REST does not enforce message format as XML or JSON.
5. The SOAP message consists of an envelope that includes SOAP headers and a body to store the actual information we want to send whereas REST uses the HTTP build-in headers (with a variety of media types) to store the information and uses the HTTP Methods such as GET, POST, PUT, PATCH, and DELETE  to perform CRUD operations.
6. SOAP Performance is slow as compared to REST.

What are the Differences between the WCF Service and Web API Service? When to choose one over the other?

The first important point is that we can use both WCF and ASP.NET Web API to develop restful services. In fact, WCF comes first, and then ASP.NET Web API.

WCF (Windows Communication Foundation) is one of the choices available in the .NET Framework for developing both SOAP and REST services. The problem with WCF is that a lot of configuration is required to turn a WCF service (SOAP service) into a REST service. So the more natural choice for developing REST services is ASP.NET Web API. In fact, ASP.NET Web API is specifically designed for this purpose i.e. for developing Restful Services.

WCF is more suitable for developing services that are transport/protocol independent. For example, our requirement is to build one service that is going to be consumed by 2 different clients – Let’s say, a Java client and a .NET client. The Java client wants the transport protocol to be HTTP and the message format to be XML for interoperability, whereas the .NET client expects the protocol to be TCP and the message format to be binary for performance. For this scenario, WCF is the right choice. What we need to do here is, create a single WCF service, and then configure 2 endpoints one for each client (i.e. one for the Java client and the other one for the .NET client).

There is nothing wrong to use WCF to develop RESTFUL services. It’s just that it’s a bit more complex and configuration can be a headache. So, if you are stuck with .NET Framework 3.5 or you have an existing SOAP service that you must support as well as you want to add REST to reach more clients, then you need to go for WCF. 

If you don’t have the limitation of .NET Framework 3.5 and you want to create a brand new restful service then go with ASP.NET Web API.

WCF

1. It is a framework used for developing SOA (service-oriented applications). 
2. WCF can only be consumed by clients, which can understand XML. WCF supports protocols like – HTTP, TCP, Named Pipes, etc.

ASP.NET Web API

1. It is a framework that helps us to develop HTTP Based services i.e. Restful Services.
2. Web API is an open-source platform.
3. It supports most of the MVC features which keep Web API over WCF.

Why Do I need to choose ASP.NET WEB API?

Nowadays, a web application is not sufficient or enough to reach all its customers. People are becoming very smart; they are using different types of devices such as mobile, iPhones, tablets, etc. in their daily life. These devices are having a lot of apps that makes their life easy. In simple words, we can say that we are moving toward the apps world from the web.

So, if we want to expose our data (business data) to the browsers as well as to all these modern devices apps in a fast, secure and simple way, then we should have an API that should be compatible with browsers as well as all these modern devices.

The ASP.NET WEB API is a great framework for building HTTP services that can be consumed by a broad range of clients including browsers, mobiles, iPhones, and tablets. 

What are the differences between ASP.NET MVC and ASP.NET Web API?

This is one of the frequently asked ASP.NET Web API Interview Questions. The following are some of the differences between ASP.NET MVC and ASP.NET Web API 

ASP.NET MVC

1. ASP.NET MVC Framework basically used to create a web application by following the MVC (Model-View-Controller) design pattern, in which we can build web pages.
2. In ASP.NET MVC, the action method can return both data and view. It only returns data in JSON format using JsonResult
3. All requests are mapped to the respective action method based on the action method names.
4. Content negotiation is not supported.

ASP.NET Web API

1. ASP.NET Web API Framework is used to develop Restful services that can be consumed by different clients.
2. ASP.NET Web API Framework returns data in JSON, XML, or any other format based on the Accept header in the request. It does not return the view to the client.
3. All requests are mapped to actions using HTTP verbs.
4. Content-negotiation supported.

Note: We can mix ASP.NET Web API and ASP.NET MVC controller in a single project to handle advanced AJAX requests which may return data in JSON, XML, or any other format, and build a full-blown HTTP service. Typically, this will be called ASP.NET Web API self-hosting. 

What are the advantages of using ASP.NET Web API?

Using ASP.NET Web API has a number of advantages, but the core advantages are as follows:

1. It supports all the HTTP features. That means you can use all the built-in HTTP Heapers such as Content-Type, Accept, Authorization, etc. and HTTP Status codes such as 500, 200, 404, etc., and HTTP verbs such as GET, POST, PUT, PATCH, and DELETE to perform CRUD operations
2. It supports Attribute Routing which is good for SEO as well as user-friendly URLs.
3. It supports content negotiation i.e. as per the client request, the server sends the response in that format (if possible). The Response is generated in JSON or XML format using MediaTypeFormatter
4. It has the ability to be hosted in IIS as well as self-host outside of IIS
5. Supports Model Binding and Validation.

What new features are introduced in ASP.NET Web API 2.0?

The new features introduced in ASP.NET Web API framework v2.0 are as follows:

1. Attribute Routing
2. External Authentication (third-party authentication)
3. CORS (Cross-Origin Resource Sharing)
4. OWIN (Open Web Interface for .NET) Self Hosting
5. IHttpActionResult Retun type

Is it true that ASP.NET Web API has replaced WCF?

It’s not true. It’s a misconception that ASP.NET Web API has replaced WCF. ASP.NET Web API is just another way of building non-SOAP-based services, for example, plain XML or JSON string, etc.

Yes, ASP.NET Web API has some added advantages like utilizing the full features of HTTP (HTTP Built-in Header and HTTP Verbs such as GET, POST, PUT, PATCH, and DELETE, HTTP Status codes such as 500, 200, 404, etc.) and reaching more clients such as mobile devices, Tables, IoTs, Browsers, etc. But WCF is still a good choice for the following scenarios:

1. If you want to develop transport protocol-oriented services other than HTTP, such as TCP, UDP, Named Pipes, etc. If HTTP only then go with Web API.
2. Message Queuing scenario using MSMQ
3. One-way communication or Duplex communication

In the next article, I am going to discuss the step-by-step procedure to Create an ASP.NET Web API Application from scratch. Here, in this article, I gave a brief introduction to ASP.NET Web API. I hope this article will help you with your needs. 

Dot Net Tutorials

About the Author: Pranaya Rout

Pranaya Rout has published more than 3,000 articles in his 11-year career. Pranaya Rout has very good experience with Microsoft Technologies, Including C#, VB, ASP.NET MVC, ASP.NET Web API, EF, EF Core, ADO.NET, LINQ, SQL Server, MYSQL, Oracle, ASP.NET Core, Cloud Computing, Microservices, Design Patterns and still learning new technologies.