Web API Best Approach for returning HttpResponseMessage

Question

I have a Web API project and right my methods always returns HttpResponseMessage.

So, if it works or fails I return:

No errors:

Answer 1

You can return an error response to provide more detail.

public HttpResponseMessage Get()
{
    HttpError myCustomError = new HttpError("The file has no content or rows to process.") { { "CustomErrorCode", 42 } };
     return Request.CreateErrorResponse(HttpStatusCode.BadRequest, myCustomError);
 }

Would return:

{ 
  "Message": "The file has no content or rows to process.", 
  "CustomErrorCode": 42 
}

More details here: http://blogs.msdn.com/b/youssefm/archive/2012/06/28/error-handling-in-asp-net-webapi.aspx

I also use http://en.wikipedia.org/wiki/List_of_HTTP_status_codes to help me determine what http status code to return.

Answer 2

One important note: Don't put content in 204 responses! Not only is it against the HTTP specification, but .NET can actually behave in unexpected manners if you do.

I mistakenly used return Request.CreateResponse(HttpStatusCode.NoContent, null); and it led to a real headache; future requests from the same session would break due to having a "null" string value prepended to the response. I guess .NET doesn't always do a full clear of the response object for API calls from the same session.

Answer 3

Although this is not directly answering the question, I wanted to provide some information I found usefull. http://weblogs.asp.net/dwahlin/archive/2013/11/11/new-features-in-asp-net-web-api-2-part-i.aspx

The HttpResponseMessage has been more or less replaced with IHttpActionResult. It is much cleaner an easier to use.

public IHttpActionResult Get()
{
     Object obj = new Object();
     if (obj == null)
         return NotFound();
     return Ok(obj);
 }

Then you can encapsulate to create custom ones. How to set custom headers when using IHttpActionResult?

I haven't found a need yet for implementing a custom result yet but when I do, I will be going this route.

Its probably very similar to do using the old one as well.

To expand further on this and provide a bit more info. You can also include messages with some of the requests. For instance.

return BadRequest("Custom Message Here");

You can't do this with many of the other ones but helps for common messages you want to send back.