Returning IHttpActionResult vs IEnumerable<Item> vs IQueryable<Item>

Question

In ASP.NET Web API 2, what is the difference among the following?

public async Task<IEnumerable<MyItem>> GetMyItems()
{
    //... code ..., var myItems = await ...
    return myItems;
}

and

public async Task<IQueryable<MyItem>> GetMyItems()
{
    //... code ..., var myItems = await ...
    return myItems;
}

and

public async Task<IHttpActionResult> GetMyItems()
{
    //... code ..., var myItems = await ...
    return Ok(myItems);
}

Should I return IHttpActionResult or IEnumerable<MyItem> / IQueryable<MyItem> ?

Answer 1

You should return IHttpActionResult because you can be more specific to the client. You can create more user friendly web applications. Basically you can return different HTML status messages for different situations.

For example:

public async Task<IHttpActionResult> GetMyItems()
{
    if(!authorized)
        return Unauthorized();
    if(myItems.Count == 0)
        return NotFound();
    //... code ..., var myItems = await ...
    return Ok(myItems);
}

IEnumerableand IQueryable will just parse your data into the output format and you will not have a proper way to handle exceptions. That is the most important difference.

Answer 2

I would choose between IEnumerable and IHttpActionResult, you can do pretty much the same thing with both of these just in slightly different ways. IQueryable is usually used for lower level data access tasks and deferred execution of sql queries so I'd keep it encapsulated within your data access classes and not expose it with the web api.

Here's a summary from http://www.asp.net/web-api/overview/web-api-routing-and-actions/action-results:

IHttpActionResult

The IHttpActionResult interface was introducted in Web API 2. Essentially, it defines an HttpResponseMessage factory. Here are some advantages of using the IHttpActionResult interface (over the HttpResponseMessage class):

• Simplifies unit testing your controllers.
• Moves common logic for creating HTTP responses into separate classes.
• Makes the intent of the controller action clearer, by hiding the low-level details of constructing the response.

IEnumerable<Item>

For all other return types, Web API uses a media formatter to serialize the return value. Web API writes the serialized value into the response body. The response status code is 200 (OK).

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

A disadvantage of this approach is that you cannot directly return an error code, such as 404. However, you can throw an HttpResponseException for error codes. For more information.

Answer 3

If you got here, you are probably looking for how to return an error status code instead of actual data in an API which returns an IEumerable.

The answer is, throw an HttpResponseException. Then there is no need to use an ActionResult which clutters up otherwise clean code.

Here is a full example from the Docs:

var resp = new HttpResponseMessage(HttpStatusCode.NotFound)
    {
        Content = new StringContent(string.Format("No product with ID = {0}", id)),
        ReasonPhrase = "Product ID Not Found"
    };
    throw new HttpResponseException(resp);

The credit for this answer goes to @JasonWatmore above. This is just to make this tip more clear as it is quite useful.