Introduction
For anyone learning ASP.NET Core, understanding controllers, routes, and endpoints is crucial. These are the building blocks of a web API or MVC application.
Controllers handle incoming requests, routes define how requests reach controllers, and endpoints determine the response sent back to clients. A proper understanding of these concepts helps you design clean, maintainable, and efficient web applications.
This article explains these concepts in a step-by-step, beginner-friendly manner, with examples suitable for beginners and web developers building APIs or full-stack applications.
What is a Controller?
A controller in ASP.NET Core is a class that handles HTTP requests. It acts as a bridge between the client and the server, processing requests, executing logic, and returning responses.
Controllers can be used in two main types of projects:
MVC Applications – Controllers return views or pages.
Web API Applications – Controllers return data in JSON, XML, or other formats.
Creating a Simple Controller
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
[HttpGet]
public IActionResult GetUsers()
{
var users = new string[] { "John", "Jane", "Rahul" };
return Ok(users);
}
}
Explanation
[ApiController] – Marks the class as a Web API controller, enabling automatic model validation and response formatting.
[Route("api/[controller]")] – Sets the route for this controller. [controller] is replaced by the controller’s name without the “Controller” suffix, i.e., Users.
GetUsers() – Handles GET requests and returns a list of users.
Understanding Routes in ASP.NET Core
A route defines the URL pattern that maps to a controller and its actions. ASP.NET Core supports two types of routing:
Conventional Routing
Attribute Routing
1. Conventional Routing
Conventional routing is defined in Program.cs or Startup.cs and follows a predefined pattern:
app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
{controller=Home} – Default controller is Home if none is specified.
{action=Index} – Default action method is Index.
{id?} – Optional parameter id.
Example URL
/Users/GetUsers
Maps to UsersController.GetUsers().
2. Attribute Routing
Attribute routing uses attributes directly on controllers and action methods to define routes:
[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
[HttpGet("all")]
public IActionResult GetAllUsers() => Ok(new[] { "John", "Jane" });
[HttpGet("{id}")]
public IActionResult GetUserById(int id) => Ok($"User {id}");
}
[HttpGet("all")] → Responds to GET /api/users/all.
[HttpGet("{id}")] → Responds to GET /api/users/1, GET /api/users/2, etc.
Understanding Endpoints
An endpoint is the final destination of a request in ASP.NET Core. It represents a combination of:
HTTP method (GET, POST, PUT, DELETE)
Route (URL pattern)
Controller action that executes the request
ASP.NET Core maps requests to endpoints using middleware and routing configurations.
Example of Multiple Endpoints
[ApiController]
[Route("api/products")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult GetAllProducts() => Ok(new[] { "Laptop", "Phone" });
[HttpPost]
public IActionResult AddProduct([FromBody] string product) => Ok($"Added {product}");
[HttpGet("{id}")]
public IActionResult GetProductById(int id) => Ok($"Product {id}");
}
Endpoints
| HTTP Method | URL | Action |
|---|
| GET | /api/products | GetAllProducts |
| POST | /api/products | AddProduct |
| GET | /api/products/1 | GetProductById |
Route Parameters
Routes can accept parameters that are passed to action methods.
[HttpGet("{id}/details")]
public IActionResult GetProductDetails(int id)
{
return Ok($"Details of product {id}");
}
Optional parameters
[HttpGet("{id?}")]
public IActionResult GetProduct(int? id)
{
return Ok(id.HasValue ? $"Product {id}" : "All Products");
}
Query Strings vs Route Parameters
Route Parameters – Part of the URL path:
GET /api/products/5
Query Strings – Appended after ? in the URL:
GET /api/products?id=5&name=Laptop
Action method
[HttpGet("search")]
public IActionResult SearchProduct(int id, string name)
{
return Ok($"Product {id} - {name}");
}
Combining Multiple Routes
You can define complex routing with multiple segments:
[HttpGet("category/{categoryId}/product/{productId}")]
public IActionResult GetCategoryProduct(int categoryId, int productId)
{
return Ok($"Category {categoryId} - Product {productId}");
}
HTTP Methods and Endpoints
ASP.NET Core supports all HTTP methods:
Example
[HttpPut("{id}")]
public IActionResult UpdateProduct(int id, [FromBody] string product)
{
return Ok($"Updated product {id} to {product}");
}
[HttpDelete("{id}")]
public IActionResult DeleteProduct(int id)
{
return Ok($"Deleted product {id}");
}
Best Practices
Use Attribute Routing for APIs: Provides clear, readable URLs.
Keep Controllers Focused: Each controller should handle a single resource (e.g., UsersController handles users).
Use HTTP Status Codes Properly: 200 for success, 201 for created, 404 for not found, 400 for bad request.
Validate Route Parameters: Avoid unexpected errors by validating input.
Consistent Naming: Use plural names for controllers (UsersController) and lowercase for URLs (/api/users).
Version Your APIs: For example, /api/v1/users to maintain backward compatibility.
Common Mistakes to Avoid
Mixing multiple resources in one controller.
Using complex URLs when simple ones suffice.
Forgetting [ApiController] attribute for APIs.
Not handling optional parameters carefully.
Returning plain strings instead of proper HTTP responses with IActionResult.
Conclusion
Understanding controllers, routes, and endpoints is the foundation of building web APIs and MVC applications in ASP.NET Core.
Controllers process requests and return responses.
Routes define how URLs map to controllers and actions.
Endpoints are the actual destinations where requests are handled.
Mastering these concepts allows you to design clean, scalable, and maintainable APIs. Once you are comfortable with these basics, you can integrate ASP.NET Core APIs with frontend frameworks like Angular, React, or Vue.js for full-stack development.