Two ways to work with HTTP responses in ApiController, HttpResponseMessage and HttpResponseException

ASP.NET Web API provides two different ways to work with manipulating HTTP response messages from within your API Controller action.

  • Throw an HttpResonseException – This exception allows you to pass in an HttpResponseMessage / set status and headers. Web API will then immediately return the response.
  • Return an HttpResponseMessage – You can simply return an HttpResponseMessage from your action.

So which  should you use when? Are they both identical? Cuong Le recently asked this question on StackOverflow.

The simple answer is no they are not the same.

The main difference between the two is this. The exception is useful to immediately stop processing and exit. For example assume I have the following code

If this code runs and I pass an id that is not present, it will immediately stop processing and return a status code of 404.

If instead I return HttpResponseMessage, the request will happily continue the rest of it’s processing and return a 404. The main difference being end the request or not.

As Darrel said, the exception is useful in cases where in some cases I want processing to continue (as in when customer is found) and in others I don’t.

The place where you might want to return HttpResponseMessage directly is in an HTTP POST to return a status code of 201 and set the location header. In that case I do want processing to continue. That would would do with this code.*

*note: If you are using the beta bits you would create a new HttpResponseMessage<Customer>. I am using the later bits however which require you to use the CreateResponse extension method off of the Request.

Above, I am creating a response which sets the status code to 201, passes in the customer, and then sets the location header.

The response is then returned and the request continues processing.

Hope this helps clarify the difference.

This entry was posted in ASP.NET Web API. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Faze Me

    Forget my question. CreateResponse is an extension method added by System.Net.Http.HttpRequestMessageExtensions

  • Faze Me

    I only found System.Net.Http.HttpResponseMessage for .NET 4.5. Is there any way to do the same with .NET 4 ? Thank you

  • http://www.facebook.com/steven.solomon.923 Steven Solomon

    Glen. Been looking at this as I had the same query.  We have a number of delegating handlers, and found that just returning a response message vs throwing a response exception did not seem to make any difference in the processing chain, so I question your assertion about bypassing the processing chain.  Given that the original thread still needs to finally know about the response or exception, I am not sure how the pipeline could be bypassed anyway.

    Congrats on your new role on the Azure team by the way.

  • Dan Konigsbach

    I hunted through a dozen web pages before I found your clear, excellent description.  Thank you!

  • http://blogs.msdn.com/gblock Glenn Block

    Richard

    There is a cost of exceptions, however in this case when you throw it you remove a bunch of processing.
    Once you return the response a bunch of things happen. Filters run, message handlers run. 

    I haven’t profiled, but my guess is that it’s after all is said and done it’s cheaper to throw the exception.

  • http://blogs.msdn.com/gblock Glenn Block

    Thanks Mark, the feedback on “usings” is a good one.  Ill try to remember that in the future :-)

  • Mark Kamoski

    The article is great.

    For anyone having a time trying to actually find these classes (like me) note that they are here…
    System.Net.Http.HttpResponseMessage

    …and here…

    System.Web.Http.HttpResponseException

    …so I hope that helps.

    (This happens on a lot of code samples. Not just yours. However, if you wish to be a better writer, then just include you using statements from the top the file when you post such samples. Again, it is not just you and your article is great– I am just mentioning it for the world-at-large, etc.)

    Thanks.

    – Mark Kamoski

  • Richard Makepeace

    What’s the trade off in performance between the cost of continuing processing and the cost of throwing an exception?  Also if I don’t throw an exception but instead return an HttpResponseMessage directly what happens to the request once the response has been returned?  I’m just trying to work out if there’s a performance difference between these approaches.