.NET Web API REST Documentation

Understanding RESTful Principles in .NET Web API

REST (Representational State Transfer) is an architectural style for designing networked applications. .NET Web API is designed to make it straightforward to build RESTful services that leverage HTTP.

Core REST Concepts

Mapping REST to .NET Web API

Building RESTful services in .NET Web API involves mapping these concepts to your application structure:

Example: Managing 'Products' Resource

Let's consider a Product resource. A typical RESTful design would expose endpoints for manipulating this resource.

GET /api/products - Retrieve a collection of products.

GET /api/products/{id} - Retrieve a specific product by its ID.

POST /api/products - Create a new product.

PUT /api/products/{id} - Update an existing product.

DELETE /api/products/{id} - Delete a specific product.

In .NET Web API, these operations are implemented within controller classes:


using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

public class ProductsController : ApiController
{
    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 }
    };

    // GET /api/products
    public IEnumerable<Product> Get()
    {
        return _products;
    }

    // GET /api/products/5
    public Product Get(int id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product == null)
        {
            throw new HttpResponseException(System.Net.HttpStatusCode.NotFound);
        }
        return product;
    }

    // POST /api/products
    public void Post([FromBody] Product product)
    {
        if (!ModelState.IsValid)
        {
            throw new HttpResponseException(System.Net.HttpStatusCode.BadRequest);
        }
        product.Id = _products.Count > 0 ? _products.Max(p => p.Id) + 1 : 1;
        _products.Add(product);
    }

    // PUT /api/products/5
    public void Put(int id, [FromBody] Product product)
    {
        if (!ModelState.IsValid)
        {
            throw new HttpResponseException(System.Net.HttpStatusCode.BadRequest);
        }

        var existingProduct = _products.FirstOrDefault(p => p.Id == id);
        if (existingProduct == null)
        {
            throw new HttpResponseException(System.Net.HttpStatusCode.NotFound);
        }

        existingProduct.Name = product.Name;
        existingProduct.Price = product.Price;
    }

    // DELETE /api/products/5
    public void Delete(int id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product == null)
        {
            throw new HttpResponseException(System.Net.HttpStatusCode.NotFound);
        }
        _products.Remove(product);
    }
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}
Note: This example uses an in-memory list for simplicity. In a real-world application, you would typically interact with a database using Entity Framework or another data access technology.

HTTP Status Codes

Proper use of HTTP status codes is crucial for RESTful services to communicate the outcome of requests effectively. Web API controllers can return specific status codes or throw HttpResponseException to indicate different results:

Key Principle: Design your API around resources and use HTTP verbs and status codes accurately to ensure interoperability and a clear understanding of the API's behavior.

Further Reading