Building RESTful APIs in ASP.NET Core: A Comprehensive Guide

REST (Representational State Transfer) is an architectural style for designing web services that use HTTP protocols for data communication. In this blog, we'll explore how to build a robust REST API using ASP.NET Core, a popular framework for building web applications and services. We'll cover the fundamentals of REST APIs, HTTP verbs, and how to implement and test APIs in ASP.NET Core.

What is a REST API?

A REST API (Application Programming Interface) is a way for two computer systems to communicate over the internet. It's an architectural style that uses HTTP protocols to define a set of constraints and rules for creating web services. REST APIs rely on a stateless, client-server protocol, and use standard HTTP methods (GET, POST, PUT, DELETE) to perform operations on resources.

HTTP verbs and Their Usage:

HTTP verbs, also known as HTTP methods, define the action that the client wants to perform on a server resource. Here are the most commonly used HTTP verbs in REST APIs:

GET: Retrieve a representation of a resource.
Example: GET /api/products/1 - Retrieves a product with an ID of 1.

POST: Create a new resource.
Example: POST /api/products - Creates a new product.

PUT: Update an existing resource.
Example: PUT /api/products/1 - Updates the product with an ID of 1.

DELETE: Remove a resource.
Example: DELETE /api/products/1 - Deletes the product with an ID of 1.

Building a REST API in ASP.NET Core:

ASP.NET Core provides a robust framework for building REST APIs. Let's create a simple API to manage a list of products:

1. Create a new ASP.NET Core Web API project in Visual Studio.

2. Define a model class for the product:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

3. Create a Product controller to handle API requests as shown below:

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private static List<Product> _products = new List<Product>
    {
        new Product { Id = 1, Name = "Product 1", Price = 100 },
        new Product { Id = 2, Name = "Product 2", Price = 200 },
        new Product { Id = 3, Name = "Product 3", Price = 300 }
    };
 
    [HttpGet]
    public IEnumerable<Product> Get()
    {
        return _products;
    }
 
    [HttpGet("{id}")]
    public ActionResult<Product> Get(int id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
 
        return product;
    }
 
    [HttpPost]
    public IActionResult Post([FromBody] Product product)
    {
        _products.Add(product);
        return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
    }
 
    [HttpPut("{id}")]
    public IActionResult Put(int id, [FromBody] Product product)
    {
        var existingProduct = _products.FirstOrDefault(p => p.Id == id);
        if (existingProduct == null)
        {
            return NotFound();
        }
 
        existingProduct.Name = product.Name;
        existingProduct.Price = product.Price;
 
        return NoContent();
    }
 
    [HttpDelete("{id}")]
    public IActionResult Delete(int id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
 
        _products.Remove(product);
        return NoContent();
    }
}

Testing APIs with Swagger

Swagger is a powerful tool for designing, building, and documenting APIs. ASP.NET Core integrates seamlessly with Swagger, allowing you to generate interactive API documentation. To enable Swagger in your ASP.NET Core project, you can use the Swashbuckle NuGet packages as shown below:

After installing the packages, configure Swagger in your Program.cs file as shown below:

//Add Swagger Service
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Products API", Version = "v1" });
});

Add the above code before builder.Build();

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Products API");
});

Add the above code before app.Run();

With Swagger enabled, you can now access interactive API documentation by navigating to /swagger in your web browser.

You should see the API in Swagger UI as shown below:

You can test the above APIs right from the Swagger UI by navigating to each API call and execute it.

Testing APIs with Postman

Postman is a popular tool for testing APIs. To test the API with Postman:

1. Open Postman and create a new request.
2. Set the request method (GET, POST, PUT, DELETE) and enter the appropriate URL (e.g., https://localhost:5001/api/products).
3. For POST and PUT requests, select "Body" and choose "raw" or "JSON" as the format. Enter the JSON representation of the product.
4. Click "Send" to execute the request.
5. Postman will display the response from the API, including the status code and any returned data.

Once you send the request from Postman, you can see the response as below:

In this article, we've explored the fundamentals of REST APIs, HTTP verbs, and how to build and test APIs in ASP.NET Core. We've covered the basics of creating a simple API, implementing CRUD operations, and testing with Swagger and Postman. Building robust REST APIs is a crucial skill for modern web development, and ASP.NET Core provides a powerful framework to achieve this. Happy Coding!