ASP.NET Core controller patterns including thin controllers, routing, parameter binding, response types, and DTOs. Use when creating or reviewing API controllers.
Controllers should be thin - they handle HTTP concerns only. All business logic belongs in services.
Each controller action should be 2-3 lines maximum:
// Good - thin controller
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById(Guid id, CancellationToken cancellationToken)
{
var result = await taskService.GetByIdAsync(id, cancellationToken);
return result is null ? NotFound() : Ok(result);
}
// Bad - fat controller with business logic
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById(Guid id)
{
if (id == Guid.Empty) return BadRequest("Invalid ID");
var task = await repository.GetByIdAsync(id);
if (task is null) return NotFound();
var response = new TaskResponse(task.Id, task.Title, task.Description);
logger.LogInformation("Retrieved task {Id}", id);
return Ok(response);
}
/api/tasks, /api/users/api/task-items[ApiController]
[Route("api/[controller]")]
public class TasksController(ITaskService taskService) : ControllerBase
{
[HttpGet]
public async Task<ActionResult<List<TaskResponse>>> GetAll(CancellationToken cancellationToken)
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById(Guid id, CancellationToken cancellationToken)
[HttpPost]
public async Task<ActionResult<TaskResponse>> Create([FromBody] CreateTaskRequest request, CancellationToken cancellationToken)
[HttpPut("{id:guid}")]
public async Task<ActionResult<TaskResponse>> Update(Guid id, [FromBody] UpdateTaskRequest request, CancellationToken cancellationToken)
[HttpDelete("{id:guid}")]
public async Task<IActionResult> Delete(Guid id, CancellationToken cancellationToken)
}
[HttpPost]
public async Task<ActionResult<TaskResponse>> Create([FromBody] CreateTaskRequest request)
[HttpGet]
public async Task<ActionResult<PagedResult<TaskResponse>>> GetAll(
[FromQuery] int page = 1,
[FromQuery] int pageSize = 10,
[FromQuery] string? status = null,
CancellationToken cancellationToken = default)
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById([FromRoute] Guid id)
// Good - explicit return type
public async Task<ActionResult<TaskResponse>> GetById(Guid id)
// Avoid - IActionResult loses type info
public async Task<IActionResult> GetById(Guid id)
// 200 OK - successful GET
return Ok(result);
// 201 Created - successful POST
return CreatedAtAction(nameof(GetById), new { id = task.Id }, response);
// 204 No Content - successful DELETE
return NoContent();
// 400 Bad Request - validation failure
return BadRequest(ModelState);
// 404 Not Found - resource doesn't exist
return NotFound();
// Request DTO - what client sends
public record CreateTaskRequest(
[Required] string Title,
string? Description);
// Response DTO - what API returns
public record TaskResponse(
Guid Id,
string Title,
string? Description,
bool IsCompleted,
DateTime CreatedAt);
// Bad - exposes internal model
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskItem>> GetById(Guid id)
// Good - uses response DTO
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById(Guid id)
public record CreateTaskRequest(
[Required]
[StringLength(200, MinimumLength = 1)]
string Title,
[StringLength(2000)]
string? Description);
With [ApiController], invalid model state returns 400 automatically - no manual checks needed.
using Microsoft.AspNetCore.Mvc;
namespace TaskApi.Controllers;
[ApiController]
[Route("api/[controller]")]
public class TasksController(ITaskService taskService) : ControllerBase
{
[HttpGet]
public async Task<ActionResult<List<TaskResponse>>> GetAll(CancellationToken cancellationToken)
{
var tasks = await taskService.GetAllAsync(cancellationToken);
return Ok(tasks);
}
[HttpGet("{id:guid}")]
public async Task<ActionResult<TaskResponse>> GetById(Guid id, CancellationToken cancellationToken)
{
var task = await taskService.GetByIdAsync(id, cancellationToken);
return task is null ? NotFound() : Ok(task);
}
[HttpPost]
public async Task<ActionResult<TaskResponse>> Create([FromBody] CreateTaskRequest request, CancellationToken cancellationToken)
{
var task = await taskService.CreateAsync(request, cancellationToken);
return CreatedAtAction(nameof(GetById), new { id = task.Id }, task);
}
[HttpPut("{id:guid}")]
public async Task<ActionResult<TaskResponse>> Update(Guid id, [FromBody] UpdateTaskRequest request, CancellationToken cancellationToken)
{
var task = await taskService.UpdateAsync(id, request, cancellationToken);
return task is null ? NotFound() : Ok(task);
}
[HttpDelete("{id:guid}")]
public async Task<IActionResult> Delete(Guid id, CancellationToken cancellationToken)
{
var deleted = await taskService.DeleteAsync(id, cancellationToken);
return deleted ? NoContent() : NotFound();
}
}