For most classic ASP.NET Web API 2 actions, return IHttpActionResult: helpers such as Ok(), NotFound(), and CreatedAtRoute() make the intended HTTP outcome clear and are straightforward to test. Return HttpResponseMessage when an endpoint needs direct, low-level control over the response. This guidance is for Web API 2 in System.Web.Http, not ASP.NET Core.
What IHttpActionResult does
Introduced in Web API 2, IHttpActionResult is essentially a factory for an HttpResponseMessage. Its single method is:
Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);An action returns a result object; later, the Web API pipeline calls ExecuteAsync to create the response message and turn it into the HTTP response. This separates choosing an outcome in controller code from constructing the underlying response. Microsoft Learn: Action Results in Web API 2
When to choose each return type
| Return type | Best fit | What it gives you |
|---|---|---|
IHttpActionResult |
Actions with common outcomes such as success, not found, accepted, or created | Readable helper calls, deferred response creation, and tests that can inspect the returned result type and content |
HttpResponseMessage |
Endpoints that need direct control over response headers, content, or other low-level details | Direct access to response-message construction; Microsoft describes this as offering substantial control over the response |
Using IHttpActionResult also lets common response-construction logic live in separate result classes rather than being repeated in controllers. Choose based on the action’s responsibility: use the higher-level result helpers when they express the outcome cleanly, and the message type when that extra control is needed. Microsoft Learn: Action Results in Web API 2
#1 Best Overall
Return common outcomes from a Web API 2 action
For a lookup, the result type makes both branches apparent:
public IHttpActionResult Get(int id)
{
Product product = _repository.Get(id);
if (product == null)
{
return NotFound();
}
return Ok(product);
}NotFound() returns a 404 result. Ok(product) returns a 200 negotiated-content result containing the product. For write actions or other outcomes, the same style covers these cases:
return CreatedAtRoute("DefaultApi", new { id = product.Id }, product); // 201
return Content(HttpStatusCode.Accepted, product); // 202
return Ok(); // 200 with no bodyThese helpers communicate the intended status at the return statement while leaving response creation to the framework. Microsoft Learn: Unit Testing Controllers in Web API
Unit-test the result without running the response pipeline
Call the controller action directly, then assert the concrete result and its data. The unit-testing guide’s approach does not execute the action result; response creation is framework behavior, separate from the controller’s decision about which result to return.
- For a successful lookup, cast to
OkNegotiatedContentResult<Product>and verify the content and product ID. - For a missing item, assert that the result is
NotFoundResult. - For an empty successful delete, assert that the result is
OkResult. - For creation, inspect
CreatedAtRouteNegotiatedContentResult<Product>, including its route name and route values.
This keeps a controller unit test focused on the action’s choice of result and payload, rather than requiring a complete HTTP response pipeline. Microsoft Learn: Unit Testing Controllers in Web API
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep the framework distinction clear
IHttpActionResult belongs to classic ASP.NET Web API 2 and the System.Web.Http framework. Do not assume that these return types or helper examples apply unchanged to ASP.NET Core, which uses different abstractions. Microsoft Learn: Action Results in Web API 2
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
