Building RESTful services with ASP.Net Core
RESTful services are an essential part of today’s software development. A wide range of clients, from web applications to mobile devices, can consume these services. ASP. NET Core provides an excellent foundation for building such services due to its open-source and cross-platform nature. By using this framework, we can easily build scalable and high-throughput services. In this blog post, we’ll learn the art of creating RESTful services using ASP. NET Core. First, we’ll learn the basics of RESTful services. After that, we’ll cover ASP. NET Core and its main features. Finally, we’ll learn how to develop RESTful services using ASP. NET Core in Visual Studio. Let’s get started!
Introduction to RESTful services
REST (representational state transfer) is an architectural style for developing applications that communicate over the network. RESTful services are based on the REST principle, which includes stateless communication, uniform interface, client-server architecture, and resource-based architecture. They have become the de facto standard for developing web APIs due to their simplicity, scalability, and widespread adoption. Below are the key components that define RESTful services:
Client-Server Architecture: RESTful services follow a client-server model, where the client and server are independent entities.
Statelessness: RESTful services are stateless. This means that each request from the client to the server is independent and contains all the information that is required on the server side to fulfill this request.
Resources and URIs: Resources are the key components in REST. Each resource is identified by a Uniform Resource Identifier (URI) and an HTTP method. Clients use this URI and HTTP method to send the request to the server. By convention, the HTTP
GETmethod is used for the read operations, thePOSTmethod is used to create a new object, thePUTmethod is used for updating, and theDELETEmethod is used for removal purposes.Representation: Resources can have multiple representations, such as JSON and XML, and clients interact with these representations rather than directly with the resource itself. Resources can have multiple representations, such as JSON and XML, and clients interact with these representations rather than directly with the resource itself.
Why use ASP.NET Core for building RESTful services?
Choosing the right framework to build RESTful services is an essential part of successful application development. ASP.NET Core is a strong choice because it comes with several advantages that make it a popular and robust choice for developers. Below are a few key features that make ASP.NET Core so well suited for building RESTful services:
Cross-platform framework: ASP.NET core is a cross-platform framework that enables developers to write code for any target machine. This means that RESTful services written in ASP.NET Core can be deployed and executed on any platform, such as Windows, Linux, and Mac.
Unified framework: ASP.NET Core unifies the MVC and Web APIs that enable developers to use the same framework and patterns to build web pages and services side by side in the same project.
Serialization support: With ASP.NET Core, services do not require any type of configuration to serialize our C# class objects in the proper JSON format to support out-of-the-box serialization.
Security: ASP.NET Core provides built-in support to secure endpoints using JSON Web Tokens. Moreover, we can integrate policy-based authorization to give more fine-grained access to resources.
OpenAPI/Swagger Integration: ASP.NET Core supports the integration of OpenAPI/Swagger, which helps us to test and explore our APIs on the fly. Moreover, it helps us generate interactive API documentation.
This set of rich features makes ASP.NET Core an excellent choice for developing scalable RESTful services. In the next section, we’ll learn how to build RESTful services using ASP.NET Core.
Building RESTful services in ASP.NET Core
Now let’s dive into how to build RESTful services in ASP.NET Core. There are two approaches to creating these services:
Minimal APIs
Controller-based services
Minimal APIs use the concept of minimal dependencies. They are used to create APIs for applications that include minimal files, features, and dependencies in ASP.NET Core. On the other hand, controller-based services use separate classes to create the services. These classes are inherited from the ControllerBase class. Let’s understand the difference between these two with the help of an example.
Let’s create a service that can be used to retrieve a list of available products to the requested users. To return the list of available products, we must have a Product class. So, let’s create a Product class as follows:
public class Product{public int Id { get; set; }public string Name { get; set; }public decimal Price { get; set; }}
In the code above, we created the Product class with three attributes—Id, Name, and Price. Next, we create the minimal API that will return the list of hard-coded products.
using WebApplication2;var builder = WebApplication.CreateBuilder(args);builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();var app = builder.Build();// Configure the HTTP request pipeline.if (app.Environment.IsDevelopment()){app.UseSwagger();app.UseSwaggerUI();}app.UseHttpsRedirection();var products = new List<Product>{new Product { Id = 1, Name = "Product A", Price = 10.99M },new Product { Id = 2, Name = "Product B", Price = 15.34M },};app.MapGet("/api/products", () => products);app.Run();
In the above code, we created a list of products at lines 19-24 and defined an endpoint using the MapGet method to return the list of products at line 26. The highlighted code is code we added, while the rest of the code is auto-generated by a template (which we will see in the next section).
Next, we’ll write the same service using a controller-based method. To do this, we write the ProductController class, as shown below.
[ApiController][Route("api/[controller]")]public class ProductController : ControllerBase{private readonly List<Product> products = new List<Product>{new() { Id = 1, Name = "Product A", Price = 10.99M },new() { Id = 2, Name = "Product B", Price = 20.49M },};[HttpGet]public ActionResult<IEnumerable<Product>> Get(){return products;}}
In this controller-based example, we have a ProductController class with a single action method that handles the GET request to retrieve a list of products. Both examples achieve the same functionality—providing a read-only endpoint to retrieve a list of products.
Now that we’ve gone over both methods for creating RESTful services using ASP.NET Core, let’s explore in detail how to create these services using the minimal API method in Visual Studio.
Creating RESTful services using Visual Studio
The following slides explain the process of creating RESTful services using the Minimal API method in Visual Studio.
Open Visual Studio and click “Create a new project,” as shown in slide 1.
Enter “web api” into the search bar, and select the “ASP.NET Core Web API” project template, as shown in slide 2.
Enter a project name and select the location, as shown in slide 3.
To create the API using the minimal method, uncheck the “Use controllers” option, as shown in slide 4. If we keep this selected, these services will use the controller-based method. Next, click the “Create" button to create the default code, which is shown in slide 5.
Create a
Productclass, as shown in slide 6.Update the code in the
Program.csfile, as shown in slide 7. This code is also explained in the previous section of this blog. Once the code is updated, start the project.After the successful execution of the project, we’ll see the swagger interface from which we can execute this service, as shown in slide 8.
That’s it! We’ve created a RESTful service using Visual Studio with minimal API methods. To test your understanding, try modifying the above steps to create a service with the controller-based method.
Wrapping up and next steps
ASP.NET Core is a powerful framework for creating RESTful services. We hope this blog has helped you understand the basic concepts of RESTful services and their creation process in .NET. To learn more about .NET and RESTful services, you may find the following Educative project and courses helpful:
