Web API Best Approach for returning HttpResponseMe

Question

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

So, if it works or fails I return:

No errors:

return Request.CreateResponse(HttpStatusCode.OK,"File was processed.");

Any error or fail

return Request.CreateResponse(HttpStatusCode.NoContent, "The file has no content or rows to process.");

When I return an object then I use:

return Request.CreateResponse(HttpStatusCode.OK, user);

I would like to know how can I return to my HTML5 client a better encapsulated respose, so I can return more information about the transaction, etc.

I was thinking on creating a custom class that can encapsulate the HttpResponseMessage but also have more data.

Does anyone have implemented something similar?

Answer 1

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 2

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 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.