Introduction to ASP.NET Core Web API

Introduction to ASP.NET Core Web API

In this article, I will provide a brief introduction to the ASP.NET Core Web API Framework. By the end of the article, you will understand the following pointers.

  1. Why Do We Need Web API?
  2. What is Web API?
  3. What is ASP.NET Core Web API?
  4. Why We Need ASP.NET Core Web API?
  5. What is Rest?
  6. What are the REST Principles?
  7. Difference Between ASP.NET Web API and ASP.NET Core Web API
Why Do We Need Web API?

Suppose you have an idea for developing and launching a product. To do this, you need to develop a website and launch this product. Then what will you do? You will develop a website using any web technologies like ASP.NET MVC, PHP, ASP.NET Core, JSP, etc., that are available on the market. Of course, you will need a database, such as MySQL, Oracle, SQL Server, etc., to store your product’s business data.

Why do we need Web APIs?

So, by combining the website and the database, you will have a fully functional, dynamic website that interacts with the database. Now, after some time, your business grows. Now, along with the website, you also want Android and iOS apps. That means you want three different applications (Website, Android, and iOS) for your business. But remember, you only have one database in the backend, which stores all the business data. So, we have three different applications and one database. So, all three applications have to interact with the same database, as shown in the image below.

ASP.NET Core Web API Tutorial

If all three applications interact directly with the database, we have some problems. Let us understand the problems first, and then we will see how to overcome the above problems.

Problems Without Web APIs:
  1. Duplicate logic for each Application: The business should have some business logic. We will write the same logic for each application type, which means repeating the same logic for each type of application. This will duplicate our code.
  2. Error-Prone Code: The business logic is written for each type of application. We have to write the code in three different applications in our example. So, you might miss some code or logic in some applications. This will add more errors to your application.
  3. Some Front-end frameworks cannot communicate directly with the Database: If you are developing the website (i.e., front-end) using the angular framework, then the angular framework cannot communicate directly with the database. Angular is a front-end framework.
  4. Hard to Maintain: This type of structure is hard to maintain. We have written the code in many places, and if we want to improve our application, we need to do the same thing in many places.

There are also many other problems that we face in this structure. Let’s see how to overcome the above problems, or we can say why we need Web APIs.

Need for Web APIs:

As you can see in the image below, we have three applications on the left and the database on the right.

ASP.NET Core Web API

We aim to establish communication between all three applications and the database. So, what will we do? We will add a new Web API Project. This Web API Project will interact with the database. As shown in the image below, all three applications will only interact with the Web API Project.

Advantages of Web API

So, the Website, Android, and iOS applications do not have direct access to the database. They only need to communicate with the Web API Project, and it is the Web API project’s responsibility to interact with the database. The entire business logic will be written in the Web API project only, so we need Web API for our project. So, Web API acts as a mediator between the Front-End and Back-End.

Advantages of Web API:

The advantages of using Web APIs are as follows:

  • Platform Independence: Web APIs can be consumed by any client that understands standard web protocols like HTTP, regardless of the underlying programming language.
  • Low Bandwidth: APIs typically exchange data using JSON or XML, which is much lighter than full HTML views, reducing the amount of data transmitted.
  • Reusability: APIs promote code reuse. Once an API is defined and implemented, it can be used by multiple clients or applications without requiring significant changes. That means we write the logic in one place, i.e., in our Web API project, and all applications will use the same logic.
  • Security: APIs can be secured using authentication and authorization mechanisms, ensuring that only Authenticated and authorized clients can access sensitive data or perform certain actions. 
  • Extend Application Functionality: Suppose, first, we develop the website. Then, we can extend and develop an Android App. Again, in the future, if you want to add another type of application, such as iOS, we don’t have to write any logic.
What is Web API?

A Web API, or Web Application Programming Interface, is a set of rules and protocols that allows different software applications to communicate with each other over the Internet. It defines the methods and data formats that applications can use to request and exchange information. Web APIs are typically based on HTTP (Hypertext Transfer Protocol) and can return data in various formats, such as JSON, XML, or others.

Web APIs typically expose a set of endpoints, which are URIs that different clients, such as web, mobile, or desktop, can call to perform specific operations, such as retrieving data or submitting data. For example, A weather service API might expose the following endpoints:

  • GET /weather/today?location=Mumbai – Retrieves today’s weather for Mumbai.
  • GET /weather/forecast?location=Mumbai&days=5 – Retrieves a 5-day weather forecast for Mumbai.

What is ASP.NET Core Web API?

ASP.NET Core Web API is a framework provided by Microsoft for building HTTP-based APIs (RESTful web services) using ASP.NET Core. It enables developers to create lightweight, fast, and scalable APIs that can be consumed by a variety of clients, including web browsers, mobile devices, and IoT devices.

ASP.NET Core Web API is cross-platform, supporting Windows, macOS, and Linux, and it uses the features of ASP.NET Core, such as dependency injection, middleware pipeline, versioning, asynchronous programming, and routing to handle HTTP requests and responses efficiently.

So, the ASP.NET Core Web API is ideal for building Restful services on top of the .NET Platform. These Web API services can then be consumed by a variety of clients, such as

  • Browsers
  • Mobile applications
  • Desktop applications
  • IOTs, etc.
Why We Need ASP.NET Core Web API?

Nowadays, a web application is not sufficient to reach all customers. People are becoming very smart; they use different types of devices, such as mobile phones, iPhones, tablets, etc., in their daily lives. These devices have many apps that make their lives easy. In simple words, we can say that we are moving toward the app world from the web.

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

The ASP.NET Core 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. ASP.NET Core Web API provides several benefits:

  • Performance: ASP.NET Core is known for its high performance and scalability, making it suitable for building high-traffic APIs. It is faster than its predecessor, ASP.NET.
  • Cross-platform: ASP.NET Core runs on Windows, Linux, and macOS, allowing developers to deploy their APIs on different operating systems.
  • Modularity: The framework is built with modularity in mind, allowing developers to include only the necessary components, which keeps the application light and responsive.
  • Modern Features: It supports modern web development features like dependency injection, middleware, and asynchronous programming.
  • Security: It includes built-in features for securing APIs, such as authentication and authorization mechanisms.
  • Integration: It easily integrates with various front-end frameworks, databases, and third-party services.
What is Rest?

REST (Representational State Transfer) is an architectural style for designing networked applications used for exchanging data over a distributed environment. With Rest, there is something called a Client and a Server, and the data will be exchanged between the client and server over a distributed environment. A Distributed Environment means the client can be on any platform like Java, .NET, PHP, etc.; 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 consume these resources (perform CRUD Operations) by using HTTP Protocol methods (GET, POST, PUT, DELETE) and URIs. For example, a RESTful API for a book management system might include endpoints like:

  • GET /books – Retrieves a list of books.
  • GET /books/{id} – Retrieves details of a specific book.
  • POST /books – Adds a new book.
  • PUT /books/{id} – Updates details of a specific book.
  • DELETE /books/{id} – Deletes a specific book.
What are the REST Principles?

The REST architectural pattern specifies a set of constraints that a system should adhere to. Here are the REST constraints or principles.

Client-Server Architecture:

The client and server should be separate entities that communicate over a standardized interface. REST applications are built around the separation of concerns between client and server. Client-server architecture separates the user interface (client) from data storage (database) and processing (server). This separation allows both sides to develop and deploy independently.

For example, in a social media platform, the client (a mobile app or web browser) interacts with the server (RESTful API) to retrieve user profiles (GET /users/{userId}), post updates (POST /posts), or upload media (POST /media). The server processes these requests and returns appropriate responses, maintaining the separation of concerns between client-side and server-side operations.

Stateless:

The stateless constraint specifies that client-server communication must be stateless between requests. That means the server should not store any information related to the client on the server. The client’s request should contain all the necessary information so that the server can identify the client and process that request. This ensures that each request can be treated independently by the server.

For example, a client querying a user’s profile would send a request like GET /users/456, including an authentication token. The server responds using only the information in the request.

Cacheable:

In real-time applications, some data provided by the server is not changed that frequently, like the list of Countries, States, Cities, Products, etc. RESTful APIs can take advantage of HTTP caching mechanisms. Responses from the server should explicitly indicate whether they can be cached by clients or not. Caching improves performance and reduces server load.

For example, when a client requests a frequently accessed resource (GET /products/{productId}), the server can include caching headers like Cache-Control or Expires in the response. Subsequent requests for the same resource can be served from the client’s cache, reducing the need to fetch data from the server again until the cache expires or is invalidated.

Resource Identification

Resource Identification means that each resource (e.g., a user, a book, an order) is uniquely identifiable by a URI (Uniform Resource Identifier). This allows each resource to be accessed and manipulated independently using standard HTTP methods.

For example, consider a blog platform where each blog post is a resource. Each post can be uniquely identified by a URI like https://example.com/posts/{postId}. Here, {postId} represents the unique identifier for each blog post.

Uniform Interface:

The Uniform Interface Constraint defines an interface between the client and the server to communicate. The four principles of the uniform interface are:

  1. Resource-based URIs: Individual resources are identified in the request using URIs.
  2. HTTP Methods: Standard methods (GET, POST, PUT, DELETE) are used to perform operations on resources.
  3. Self-Descriptive Messages: Each message includes enough information to describe how to process the request, i.e., whether to fetch the data, update the data, add a new entity, delete an entity, etc.
  4. Hypermedia as the Engine of Application State (HATEOAS): Clients interact with the application entirely through hypermedia provided, such as body contents, query-string parameters, request headers, and the requested URI (the resource name).

For example, using HTTP methods such as GET, POST, PUT, and DELETE, clients can interact uniformly:

  • GET /books to retrieve a list of books.
  • GET /books/123 retrieves the book with ID 123.
  • POST /books to create a new book.
  • PUT /books/123 updates the book with ID 123.
  • DELETE /books/123 deletes the book with ID 123.
Content Negotiation:

Clients and servers should be able to negotiate the representation of a resource based on client preferences or capabilities. The client specifies its preferences using the Accept header, and the server responds with the appropriate format if it supports it.

For example, a RESTful API for a news website can provide news articles in both JSON and XML formats. When a client sends a request (GET /articles/{articleId}), it can include an Accept header (Accept: application/json) to specify that it prefers JSON format. The server then responds with the requested article in JSON format (Content-Type: application/json) if it supports it, ensuring flexibility in how clients consume resources.

Layered System:

A Layered System architecture allows an API to be composed of multiple layers, such as security, caching, load balancing, and data storage. Each layer is unaware of the other layers except for the one it directly interacts with. For example, we deploy the APIs in server A, store data on server B, and authenticate requests in server C. A client cannot simply tell whether it is connected directly to the server or an intermediary.

For example, consider an e-commerce application where clients interact with a web server that communicates with a database server. The client is unaware of the database server; it only interacts with the web server via HTTP requests. The web server, in turn, interacts with the database server to fetch and store data.

Code on Demand (Optional)

Code on Demand allows servers to extend the functionality of clients by sending executable code (like JavaScript) to clients, which the client can execute locally. This is an optional constraint and is used to add flexibility to the client.

For example, a RESTful service might provide filtering logic as JavaScript code, which a client can execute locally to dynamically adjust the interface based on certain criteria, reducing server load and improving user experience.

Difference Between ASP.NET Web API and ASP.NET Core Web API

ASP.NET Web API and ASP.NET Core Web API represent two different approaches to building Web APIs (Restful Services) within the ASP.NET framework, with several key distinctions:

Platform Support:
  • ASP.NET Web API: It is built on the .NET Framework, which means it runs only on Windows operating systems.
  • ASP.NET Core Web API: It is part of the ASP.NET Core framework, which runs on .NET Core. This allows it to be cross-platform, operating on Windows, Linux, and macOS. This is a significant advantage for developers aiming for broader application deployment across various environments.
Performance
  • ASP.NET Web API: While efficient, it does not match the performance improvements that have been realized in ASP.NET Core, mainly due to the older architecture and its dependence on the .NET Framework.
  • ASP.NET Core Web API: Designed to be lightweight and high-performance. ASP.NET Core has been optimized from the ground up to be faster and more modular. It can handle more requests per second and uses fewer resources because of its ability to support asynchronous programming more extensively.
API Design Features
  • ASP.NET Web API: Supports RESTful services but does not have native support for features like versioning and response compression without additional packages or libraries.
  • ASP.NET Core Web API: Includes built-in support for advanced API design features, such as API versioning, response caching, and response compression, making it easier to build robust APIs.
Configuration and Hosting
  • ASP.NET Web API: Typically hosted in IIS (Internet Information Services), it heavily relies on system configuration through web.config files for both application settings and dependency configurations.
  • ASP.NET Core Web API: Offers more flexibility in hosting options. It can be hosted in IIS, Kestrel (a cross-platform web server built for ASP.NET Core), or even in Docker containers. Configuration can be achieved through various sources like JSON files, environment variables, command-line arguments, etc., without relying on web.config.
Dependency Injection
  • ASP.NET Web API: Supports dependency injection, but it is not built into the framework. Developers often need to use third-party libraries like Unity or Ninject to achieve dependency injection.
  • ASP.NET Core Web API: Dependency injection is a first-class citizen in ASP.NET Core. The framework has built-in support for dependency injection, which promotes more loosely coupled code and better manageability.
Middleware Support
  • ASP.NET Web API: This does not have middleware support the way ASP.NET Core does. Custom handlers and modules can be created, but they are generally more complex to implement and integrate.
  • ASP.NET Core Web API: Uses a middleware pipeline that is easy to customize and configure. Middleware components can be used to execute code before and after your application handles a request, enabling scenarios like authentication, error handling, and logging with less complexity.
Community and Future Support
  • ASP.NET Web API: While still supported, it is part of the older .NET Framework, which does not receive new feature updates; it only receives bug fixes and security updates.
  • ASP.NET Core Web API: Being part of ASP.NET Core, it benefits from active development and new features. The community and Microsoft’s focus are more on ASP.NET Core due to its modern architecture and flexibility.
Choosing Between ASP.NET Web API and ASP.NET Core Web API:
  • Platform Requirements: If you need cross-platform compatibility or want to deploy on Linux or macOS, ASP.NET Core Web API is the better choice.
  • Performance: For applications requiring high performance and scalability, ASP.NET Core Web API is generally preferred due to its lightweight nature and optimized performance.
  • Legacy Systems: If you are maintaining or integrating with older systems built on .NET Framework, ASP.NET Web API might still be necessary due to compatibility requirements.

In the next article, I will discuss HTTP (Hyper Text Transport Protocol), i.e., HTTP Verbs or Methods, HTTP Status Codes, HTTP Requests, and Responses. Here, in this article, I try to give a brief introduction to the ASP.NET Core Web API Framework. I hope you enjoy this Introduction to ASP.NET Core Web API article.

4 thoughts on “Introduction to ASP.NET Core Web API”

Leave a Reply

Your email address will not be published. Required fields are marked *