What is the difference between HttpResponseMessage and HttpResponseException

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

public class CustomerController : ApiController {
  private ICustomerContext repo;

  public CustomerController(ICustomerContext repo) {
    this.repo = repo;
  }

  public Customer Get(int id) {
    var customer = repo.Customers.SingleOrDefault(c=>c.CustomerID == id);
    if (customer == null) {
      throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound));
    }
    return customer;
  }
}

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 its 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 use something like HttpResponseMessage 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.*

public class CustomerController : ApiController {
  private ICustomerContext repo;

  public CustomerController(ICustomerContext repo) {
    this.repo = repo;
  }

  public HttpResponseMessage Post(Customer customer) {
    repo.Add(customer);
    repo.SaveChanges();
    var response = Request.CreateResponse(HttpStatusCode.Created, customer);
    response.Headers.Location = new Uri(Request.RequestUri, string.format("customer/{0}", customer.id));
    return response;
  }
}

*note: If you are using the beta bits you would create a new HttpResponseMessage. 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

HttpResponseException is useful when your Controller Action signature looks like

  Foo Get(int id)

In this case, you cannot easily return status code like 400.

Be aware that HttpResponseMessage<T> is going away in the next release of Web API.

Assuming you want to unit test the responses, doesn't it make sense to always return an HttpResponseMessage? I don't particularly like the idea of returning a straight type from an ApiController since it doesn't follow typical development patterns.

In a non-Web API class that fetched a Customer, you'd likely return null, with your calling code checking for a null response:

public Customer GetCustomer(int id)
{
    return db.Customers.Find(id);
}

But in Web API, you're not going to return null, you have to return something, even if that something is created after you throw an HttpResponseException. In that case, to ease testing, why not just always return an HttpResponseMessage, and make that your signature?

public HttpResponseMessage GetCustomer(int id)
{
    var customer = db.Customers.Find(id);
    if (customer == null)
    {
        return Request.CreateResponse(HttpStatusCode.NotFound);
    }

    return Request.CreateResponse(HttpStatusCode.OK, customer);
}