Matthew Jones

Good morning everyone, and welcome to the new HTTP Status Codes in ASP.NET Web API tour here at Exception Not Found! My name is Reggie, and I'll be your tour guide today. Those of you who have taken our Exception Handling tour, welcome back! For those of you who are new to our facility, thank you for visiting us.

First off, I'd like to introduce my brilliant assistant Postman, who will be assisting me on this tour. Also assisting us will be Nathan, and he'll be doing whatever I need him to, and he better be grateful, this is his last chance, that little...

As I said, Nathan will be assisting us, since we have such a large group. This tour moves fast, so please keep up. Today, we're going to take a look around at the variety of status codes we can return from our Web API applications. Step right this way, stay together, and let's learn about what HTTP status codes are and how we use them in our ASP.NET Web API projects.

The Types of Status Codes

HTTP implements a wide variety of status codes, which are grouped into five categories. The five categories are distinguished by the code's first number, like so:

3XX Codes: Redirect codes. Tells the client that they may need to redirect to another location.

4XX Codes: Client Error codes. Tells the client that something was wrong with what it sent to the server.

5XX Codes: Server Error codes. Tells the client that something went wrong on the server's side, so that the client may attempt the request again, possibly at a later time.

ASP.NET Web API can return any of those codes, though the more common ones have simpler return methods. Up next, we will show how we can determine what the proper code is to return from our action methods. This way, please.

Selecting the Proper Code

You should know that there is no "one true way" of selecting the proper status code; it all depends on your business rules. That said, unless your rules state otherwise, it is usually a good idea to return a more specific code rather than a more generic one.

As an example, consider a situation where your server needs to tell the client that a request that was submitted to it didn't have the proper authorization. One status code you could return is 400 Bad Request, as this implies that the request submitted was improper and not processed by the server. However, a more specific error code would be 401 Unauthorized, since that explicitly states what was wrong with the request. You should use more specific codes unless you have a business or security reason not to.

So, now we can start talking about what ASP.NET Web API does when it implements actions. If you'll just follow me to the next hallway, we can start to see code that shows what Web API will do in certain common situations.

Return Void - 204 No Content

Nathan, not that display case. Go to the other one. No, the other other one. YES THAT ONE.

Ahem! Take a look at the display case next to where Nathan is standing. Inside, we have one of our sample controllers:

You'll notice that this controller only has one action, which returns void. Postman, can you show us what the response looks like when we call this action please?

When we call this action, we'll see that ASP.NET returns a status code of 204 - No Content. Since HTTP doesn't understand void, this is the appropriate status code. One of the many features we provide, at no extra charge!

But, what happens if we want to return something a little more complex? If you'll follow me right over here, we can see a sample.

Now our action is returning an object. Postman, what kind of response do we get when calling this action?

Now we get 200 - OK as the status code. But we didn't tell ASP.NET to return this code, so why did it?

Because if you return any serializable object from a Web API action, the response automatically becomes 200 - OK, with the object written in to the response body. Of course, if you wanted to explicitly specify that return code, all you would need to do is change the return type and return statement, like so:

Pardon the action name, we seem to have had a little... difficulty in setting up this display. Rest assured, whatever you name the action, you can use the shortcut method Ok() to return the status code 200 - OK.

Let's hurry along to the next display cabinet, where we will see some other shortcut methods we can use to represent commonly-returned status codes.

Shortcut Methods

I've been using the term "shortcut methods" to refer to a set of methods that return classes which implement IHttpActionResult. The next display cabinet has a few others, each of which represent common HTTP status codes:

BadRequest(): Returns 400 - Bad Request.

NotFound(): Returns 404 - Not Found.

InternalServerError(): Returns 500 - Internal Server Error.

There's also a catchall method, one that can return any HTTP status code:

HttpStatusCode is an enumeration, whose values can be found over in the Status Codes exhibit. As you see at later points in this tour, HttpStatusCode becomes very useful when trying to return other, less common status from your API.

For now, let's continue down this hallway to see another method by which we can return status codes.

HttpResponseMessage

Though the shortcut methods are useful for common scenarios, they don't cover all possible status codes.... My apologies, please wait here a moment.

Nathan! Mrs. George does NOT need to be shown to the "bodily functions" display. No, it is not "interesting" or "transformative" it is gross and it doesn't even belong to this museum. Now come here! I swear, if your mother wasn't my sister...

As I was saying, the shortcut methods don't cover all possible status codes. For example, the red display in front of you has a method that should return 304 Not Modified:

HttpResponseMessage represents the response from the server to the client, and can be used with any of the status codes in the HttpStatusCode enumeration. In this way, we can return any of the standard status codes.

NotImplementedException is a .NET Exception that specifies that a given method is not implemented. However, HTTP does not understand .NET exceptions, so Web API will return an error code to a client that calls this method. The error code returned is 500 - Internal Server Error.

We like to say that returning 500 is the equivalent of the server throwing up its hands and saying "well, that didn't work." In other words, it's not a very useful status code. For situations where you don't want to give extra information to client (e.g. public-facing services that could be hit by malicious users) this may be exactly what you want. However, in many other scenarios there is a more appropriate status code to return: 501 Not Implemented.