ASP.NET Core Web APIs

Introduction to ASP.NET Core Web APIs

ASP.NET Core Web APIs enable you to build RESTful HTTP services that can be consumed by a wide range of clients, including single-page applications (SPAs), mobile apps, and other backend services. They are a fundamental part of modern web development, providing a robust and scalable way to expose data and functionality over the web.

Key benefits of using ASP.NET Core for Web APIs include:

• Cross-Platform: Runs on Windows, macOS, and Linux.
• High Performance: Designed for speed and efficiency.
• Modular and Light-weight: You only include what you need.
• Unified Model: Common patterns for building web UI and web APIs.
• Open Source and Community-driven: Constantly evolving with community contributions.

Getting Started

To start building Web APIs with ASP.NET Core, you'll need the .NET SDK installed. You can create a new Web API project using the .NET CLI:

dotnet new webapi -o MyAwesomeApi
cd MyAwesomeApi
dotnet run

This command creates a new project directory named MyAwesomeApi with a basic Web API template, including a sample controller and configuration.

Controllers and Actions

In ASP.NET Core, Web APIs are built using controllers. A controller is a class that handles incoming HTTP requests and returns HTTP responses. Controller actions are public methods within a controller class that are mapped to specific HTTP requests.

Sample Controller

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using YourNamespace.Models; // Assuming you have a Product model

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private static List<Product> _products = new List<Product>
    {
        new Product { Id = 1, Name = "Laptop", Price = 1200.00M },
        new Product { Id = 2, Name = "Keyboard", Price = 75.00M }
    };

    [HttpGet]
    public ActionResult<IEnumerable<Product>> GetAllProducts()
    {
        return Ok(_products);
    }

    [HttpGet("{id}")]
    public ActionResult<Product> GetProductById(int id)
    {
        var product = _products.Find(p => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
        return Ok(product);
    }

    [HttpPost]
    public ActionResult<Product> CreateProduct(Product newProduct)
    {
        newProduct.Id = _products.Count + 1;
        _products.Add(newProduct);
        return CreatedAtAction(nameof(GetProductById), new { id = newProduct.Id }, newProduct);
    }
}

namespace YourNamespace.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public decimal Price { get; set; }
    }
}

The [ApiController] attribute enables API-specific behaviors, and [Route("api/[controller]")] sets up a convention for routing. [HttpGet], [HttpPost], etc., specify the HTTP methods the action handles.

Routing

Routing determines how incoming requests are mapped to controller actions. ASP.NET Core uses a convention-based routing system by default. The [Route] attribute on controllers and actions defines these routes.

• Attribute Routing: Explicitly defines routes using attributes like [HttpGet], [HttpPost], [Route].
• Convention-based Routing: Configured in Program.cs (or Startup.cs in older versions).

In the example above, [Route("api/[controller]")] on the controller and [HttpGet] on the action create routes like /api/products for getting all products and /api/products/{id} for getting a specific product.

Data Binding

Data binding is the process of mapping incoming HTTP request data (like query strings, route parameters, request bodies, or form data) to parameters of your controller actions.

• [FromRoute]: Binds from route data (e.g., {id} in /api/products/{id}).
• [FromQuery]: Binds from the query string (e.g., ?name=Laptop).
• [FromBody]: Binds from the request body, typically JSON or XML.
• [FromForm]: Binds from form data.
• [FromServices]: Binds from dependency injection.

If no attribute is specified, ASP.NET Core tries to infer the binding source.

Request Processing

ASP.NET Core's request pipeline processes incoming requests. Middleware components handle various aspects, such as routing, authentication, authorization, and request/response manipulation.

The core components for API development include:

• Routing Middleware: Selects the appropriate controller action.
• Model Binding: Populates action parameters.
• Action Execution: Calls the controller action method.
• Result Execution: Converts the action's return value into an HTTP response.

Response Generation

Controller actions return results that are converted into HTTP responses. Common return types and helpers include:

• ActionResult<T>: A flexible return type that can represent either a specific type T or an IActionResult.
• IActionResult implementations:
  • OkResult / Ok(value): Returns an HTTP 200 OK status with an optional value.
  • NotFoundResult / NotFound(): Returns an HTTP 404 Not Found status.
  • BadRequestResult / BadRequest(error): Returns an HTTP 400 Bad Request status.
  • CreatedAtAction(actionName, routeValues, value): Returns an HTTP 201 Created status, often with a Location header pointing to the newly created resource.
  • NoContentResult: Returns an HTTP 204 No Content status.

By default, ASP.NET Core uses JSON serializers for request and response bodies.

Authentication and Authorization

Securing your Web APIs is crucial. ASP.NET Core provides robust support for:

• Authentication: Verifying the identity of the user or client making the request. This can be done via cookies, JWT tokens, OAuth, API keys, etc.
• Authorization: Determining if an authenticated user has permission to perform a specific action.

You configure these in Program.cs and apply attributes like [Authorize] to controllers or actions.

Testing APIs

Writing unit and integration tests for your Web APIs ensures their reliability and correctness.

• Unit Tests: Test individual components in isolation.
• Integration Tests: Test the API as a whole, including the request pipeline and controller logic, often using the TestServer provided by the Microsoft.AspNetCore.Mvc.Testing NuGet package.

Tools like Postman or Swagger UI (with Swashbuckle) are invaluable for manual testing and exploration.

Deployment

ASP.NET Core Web APIs can be deployed to various environments:

• IIS: On Windows servers.
• Kestrel: ASP.NET Core's built-in web server, often behind a reverse proxy like Nginx or Apache.
• Cloud Platforms: Azure App Service, AWS Elastic Beanstalk, Docker containers, Kubernetes.

The dotnet publish command creates deployment-ready artifacts.