dotnet-web-api

ASP.NET Core Web API

Trigger On

• working on controller-based APIs in ASP.NET Core
• needing controller-specific extensibility or conventions
• migrating or reviewing existing API controllers and filters

Workflow

1. Use controllers when the API needs controller-centric features, not simply because older templates did so.
2. Keep controllers thin: map HTTP concerns to application services or handlers, and avoid embedding data access and business rules directly in actions.
3. Use clear DTO boundaries, explicit validation, and predictable HTTP status behavior.
4. Review authentication and authorization at both controller and endpoint levels so the API surface is not accidentally inconsistent.
5. Keep OpenAPI generation, versioning, and error contract behavior deliberate rather than incidental.
6. Use dotnet-minimal-apis for new simple APIs instead of defaulting to controllers out of habit.

Deliver

• controller APIs with explicit contracts and policies
• reduced controller bloat
• tests or smoke checks for critical API behavior

Validate

• controller features are actually justified
• actions do not hide business logic and persistence details
• HTTP semantics stay predictable across endpoints

Controller Structure

Use primary constructors (C# 12+) for dependency injection and keep controllers focused on HTTP concerns:

[ApiController]
[Route("api/[controller]")]
public class OrdersController(
    IOrderService orderService,
    ILogger<OrdersController> logger) : ControllerBase
{
    [HttpGet("{id:guid}")]
    [ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
    {
        var order = await orderService.GetByIdAsync(id, ct);
        return order is null ? NotFound() : Ok(order);
    }

    [HttpPost]
    [ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create(CreateOrderRequest request, CancellationToken ct)
    {
        var order = await orderService.CreateAsync(request, ct);
        return CreatedAtAction(nameof(GetById), new { id = order.Id }, order);
    }
}