ControllerBase — HTTP Responses and Helper Methods

ControllerBase (the base class for Web API controllers) provides helper methods for every common HTTP response type. Using these helpers rather than manually constructing ObjectResult with status codes keeps action methods readable and correct. The ActionResult<T> generic return type combines type safety for the happy-path response with flexibility for error responses — Swagger documents the response type automatically, and you return either the DTO or an error result.

Complete CRUD Controller #

[ApiController]
[Route("api/posts")]
public class PostsController(IPostService service) : ControllerBase
{
    // GET api/posts?page=1&size=10
    [HttpGet]
    [ProducesResponseType(typeof(PagedResult<PostSummaryDto>), 200)]
    public async Task<ActionResult<PagedResult<PostSummaryDto>>> GetAll(
        [FromQuery] int page = 1,
        [FromQuery] int size = 10,
        CancellationToken ct = default)
    {
        var result = await service.GetPageAsync(page, size, ct);
        return Ok(result);   // 200 with PagedResult body
    }

    // GET api/posts/42
    [HttpGet("{id:int}", Name = "GetPostById")]
    [ProducesResponseType(typeof(PostDto), 200)]
    [ProducesResponseType(404)]
    public async Task<ActionResult<PostDto>> GetById(int id, CancellationToken ct)
    {
        var post = await service.GetByIdAsync(id, ct);
        return post is null ? NotFound() : Ok(post);   // 200 or 404
    }

    // POST api/posts
    [HttpPost]
    [ProducesResponseType(typeof(PostDto), 201)]
    [ProducesResponseType(typeof(ValidationProblemDetails), 400)]
    public async Task<ActionResult<PostDto>> Create(
        CreatePostRequest request,
        CancellationToken ct)
    {
        var post = await service.CreateAsync(request, ct);

        // 201 Created + Location header pointing to the new resource
        return CreatedAtAction(nameof(GetById), new { id = post.Id }, post);
    }

    // PUT api/posts/42
    [HttpPut("{id:int}")]
    [ProducesResponseType(typeof(PostDto), 200)]
    [ProducesResponseType(404)]
    public async Task<ActionResult<PostDto>> Update(
        int id, UpdatePostRequest request, CancellationToken ct)
    {
        var post = await service.UpdateAsync(id, request, ct);
        return post is null ? NotFound() : Ok(post);
    }

    // DELETE api/posts/42
    [HttpDelete("{id:int}")]
    [ProducesResponseType(204)]
    [ProducesResponseType(404)]
    public async Task<IActionResult> Delete(int id, CancellationToken ct)
    {
        var existed = await service.DeleteAsync(id, ct);
        return existed ? NoContent() : NotFound();   // 204 or 404
    }
}

ControllerBase Helper Methods Reference #

Common Mistakes #

Mistake 1 — Using Ok() for creation (should be Created/CreatedAtAction) #

❌ Wrong — 200 OK for a POST that created a resource; no Location header.

✅ Correct — always return 201 with a Location header for successful POST operations.

Mistake 2 — Returning 200 with a null body for successful DELETE (should be 204) #

❌ Wrong — return Ok() for DELETE; returns 200 with an empty body.

✅ Correct — return NoContent() for DELETE; returns 204 with no body, correctly signalling success with no response data.