In this article, we will discuss the difference between RESTful APIs and Web APIs using the ASP.NET Core framework.
We’ll begin by explaining what exactly an API is. Then, we’ll explain the meaning of REST and RESTful. After that, we will delve into Web APIs. Finally, we’ll round things up by summarizing the difference between a RESTful API and a Web API.
Let’s dive in!
What Is an API?
To start, let’s look at what an API is.
When we interact with a computer, we usually do it through a user interface (UI). Similarly, when we aim to have two software applications interact with each other, we need some sort of interface. We commonly refer to this interface as an API.
An API (Application Programming Interface) is a set of conventions and features, essentially an interface, that enables communication between two software programs. We can invoke these features either on the same machine or remotely.
We can think of an API as a middleman within our application. For instance, let’s imagine we have a books website with a button that, when clicked, fetches and displays all the books from our database. Now, when a user interacts with this button, they trigger a request. In the background, our API comes into play. It takes the request from the webpage, communicates with the server, receives a response containing the list of books, and then displays it to the user.
We also make use of APIs when we develop applications that use third-party services from companies like AWS and Facebook. These companies provide us with APIs — code constructs and conventions written in a programming language. We then use these APIs to query their servers and receive responses. Through APIs, we can leverage already-existing functionalities in external applications, without having to build our implementation of that functionality, thereby saving time and money.
Alright. Now, let’s explain the concepts of REST and RESTful.
What Is REST and RESTful?
As software developers, when we create APIs, there are various software architectural styles available for us to use. These styles provide us with rules and constraints to build highly performant, portable, reliable, scalable, and maintainable APIs.
REST, short for Representational State Transfer, is one such architectural style. In an application that follows the REST style, we interact with resources (entities) such as employees, books, and teachers. Our clients and servers in this type of application communicate through a standardized representation. These representations include JSON and XML, which contain information about the state of the resource.
First introduced in 2000 by Roy Fielding, REST describes six fundamental constraints guiding communication between software programs to ensure their interactions are loosely coupled, maintainable, and scalable.
These constraints include:
- A client-server architecture where clients and servers are separate entities
- A uniform interface between components
- Statelessness of client-server interaction
- Cache-ability of data from the server
- The ability of the server to send executable code on demand by the client (This constraint is optional)
- A layered system that allows for the separation of concerns
Complying with the REST constraints allows us to build applications that are simple, scalable, portable, and reliable.
With this background, let’s now discuss the meaning of RESTful.
We can say that our application is RESTful if it satisfies the six REST architectural constraints. However, if our application violates any of the constraints except the code-on-demand constraint, it is not strictly RESTful.
RESTful APIs
Now, from our definition of a RESTful application, we can describe a RESTful API or RESTful Web API as any API that adheres to the six constraints of REST. These APIs typically use standards like JSON and XML for data transfer.
In practice, when we talk about RESTful APIs, we usually mean web-based APIs that utilize HTTP for communication and align with REST guidelines.
Moreover, these APIs enable us to query web servers through HTTP requests and receive responses in JSON or XML format. Some examples of RESTful web APIs include Twitter API, Microsoft Graph API, and Facebook API.
Alright. Now, let’s look at what an ASP.NET Core Web API is.
ASP.NET Core Web APIs
To simplify the process of creating RESTful web APIs with C#, Microsoft developed the ASP.NET Core Web API framework. With this cross-platform and open-source framework, we can quickly set up, test, and deploy RESTful APIs. We can also access the APIs we create with this framework from various clients like web applications, mobile apps, games, desktop apps, or other web APIs.
We should note that building a web API with C# using ASP.NET Core Web API provides several advantages. These include a built-in logging system, easy database integration, support for versioning, and easy implementation of an authentication system. Additionally, it allows the addition of Swagger for API documentation, enables working with Cross-Origin Resource Sharing (CORS), uses standard HTTP verbs, and features a robust routing system.
Create a RESTful Web API With ASP.NET Core
For illustration purposes, let’s create a RESTful Web API with ASP.NET Core:
[Route("api/books")]
[ApiController]
public class BooksController(IBookService bookService) : ControllerBase
{
private readonly IBookService _bookService = bookService;
[HttpGet]
public IActionResult GetAllBooks() => Ok(_bookService.GetAllBooks());
}
In this API, we define a controller that inherits from the ControllerBase class. Within the controller, we instantiate an IBookService object. Subsequently, we create an HTTP GET method named GetAllBooks() to retrieve all the books from our database. We use the HttpGet attribute to indicate that we want this method to handle HTTP GET requests.
By default, all ASP.NET Core Web APIs are RESTful. However, let’s explore some of the principles our API follows.
Firstly, the [ApiController] and [Route("api/books")] attributes enable us to adhere to the uniform interface constraint by providing a predictable and uniform URI route.
Next, this API conforms to the client-server architecture constraint, with our server responsible solely for handling user requests and returning responses, while the client manages the user interface and experience.
Lastly, communication between our server and client is stateless because our GET request contains all the information the server needs to return our list of books. We do not rely on data from previous requests, and we do not store session data after our request.
Now, although our API lacks a definition for cache-ability, code-on-demand, and a layered system, the ASP.NET Core architecture allows us to scale it to meet these guidelines.
So that’s it. Let’s now summarize the difference between a RESTful API and a Web API.
Summary of Approaches
In summary, a RESTful API is an API that adheres to the six REST guidelines. We usually access them through the web using HTTP and often call them RESTful web APIs.
On the other hand, Web API is a cross-platform and open-source framework within the .NET ecosystem. We use it to create RESTful web APIs and call it the ASP.NET Core Web API framework.
Conclusion
In this article, we have successfully explained the difference between RESTful APIs and Web APIs using ASP.NET Core.
We started by defining an API as an interface that enables communication between two software programs. Then, we learned that a RESTful API is an API that follows the REST principles. We noted that we access these APIs through the web via HTTP and often refer to them as RESTful web APIs.
Finally, we identified ASP.NET Core Web API as an open-source and cross-platform framework developed by Microsoft for creating RESTful web APIs.