ASP.NET Web API - return CLR object or HttpResponseMessage

Question

What seems to be general practice in Web API for return types from action methods?

Returning CLR objects like so:

public IEnumerable<ContactModel> Get()
{
    return _contactService.GetAllForUser();
}

Or wrapping your object in a HttpResponseMessage:

public HttpResponseMessage Get()
{
    IEnumerable<ContactModel> contacts = _contactService.GetAllForUser();

    return Request.CreateResponse((HttpStatusCode) 200, contacts);
}

I prefer having my own CLR objects as the return type as it is obviously results in cleaner methods, as you don't have to mess around instantiating a HttpResponseMessage every time.

Answer 1

The important point here is that this choice is a matter of PREFERENCE. If you are creating a "URI-Style" HTTP api where the return types are known, in advance, by the client then this may be your preferred approach.

However, personally, I don't like returning CLR types. I believe that by taking this approach you are likely to lose many of the benefits of HTTP. I always return HttpResponseMessage.

If you consider a standard procedure call, there are two possible outcomes, you get the return type back or you get an exception. HTTP interactions are far more flexible than that due to redirects, temporary unavailable servers, no-content, not-modified, server conneg, prefer header variants, etc.

I think that the ApiController class is the place where your application gets the chance to map object-oriented method calls into HTTP request/responses. I think doing this mapping explicitly facilitates taking advantage of HTTP. Letting the framework magically convert the CLR type into some wire representation, does save some typing, but it obscures what is happening and forces you to do any kind of HTTP interactions indirectly through ActionFilters and MessageHandlers.

I have no interest in convincing people who would prefer to return CLR types to change, I simply want to re-assure people who like the idea of returning HttpResponseMessage that it is a completely viable option despite the fact that you will not see many samples like that.

Answer 2

I think the first option is the best. In any case if there is no error the return code will be 200 without any setting on your side.

If there is any exception you could throw a HttpResponseException with the appropiate code and message

throw new HttpResponseException(
    Request.CreateResponse<string>(HttpStatusCode.BadRequest, 'Your message'))