Web API Deep Dive - HTTP Error Codes from Exceptions (Part 3 of 6)

Microsoft’s ASP.Net Web API 2.2 allows you to easily create REST style APIs on an IIS website. Microsoft has some great documentation on how to get started with it, so I won’t rehash that here. Instead, I’m going to go a little deeper into some powerful features that can be used with Web API.

HTTP Error Codes from Exceptions

In the last post, we looked at how you can specify HTTP Response codes to return from your API controller when everything is working properly. However, sometimes a problem will occur deep inside your code. Continuing down the REST path, when problems occur, you should use the semantics of HTTP by returning an HTTP status code that reflects the error. When problems occur in your code, exceptions are typically thrown. This week we will be looking at how we can specify the HTTP Response code and content to return depending on the exception that is thrown.

Feb 10, 2016 Update - Fixed bug in second code block

This is a matter of style, but the first thing that I like to do is to create a custom exception, so that I know that what I’m doing will only apply when I specifically raise my custom exception.

Read More

Web API Deep Dive – HTTP Response Codes (Part 2 of 6)

Microsoft’s ASP.Net Web API 2.2 allows you to easily create REST style APIs on an IIS website. Microsoft has some great documentation on how to get started with it, so I won’t rehash that here. Instead, I’m going to go a little deeper into some powerful features that can be used with Web API.

Part 1 - Customizing auto-generated documentation
Part 2 - HTTP Response Codes (this article)
Part 3 - HTTP Error Codes from Exceptions
Part 4 - OData URL Query Options
Part 5 - DTO Transformations and Automapper
Part 6 - Testing with EF Rollbacks across HTTP

Using Appropriate HTTP Response Codes

When building an HTTP REST API, you should use appropriate HTTP response codes to indicate the status of a response. This uses the semantics of HTTP to communicate the status rather than inventing something new. Here are the three response codes I use most often:

HTTP 200 - Everything is OK
HTTP 201 - Something was created
HTTP 404 - Something could not be found

I only explicitly do this for methods that return a single object. For Web API methods that return a collection, I don’t worry about what’s written in this blog post. That’s because if I successfully return a collection, Web API will by default return HTTP 200 OK. If it can’t find any items, I return an empty collection, which still by default returns HTTP 200 OK. And if there is an error, the error handling filter returns the appropriate HTTP Status code for the error (more details on this in next week’s post).

Read More

Web API Deep Dive - Customizing Auto-Generated Documentation (Part 1 of 6)

Microsoft’s ASP.Net Web API 2.2 allows you to easily create REST style APIs on an IIS website. Microsoft has some great documentation on how to get started with it, so I won’t rehash that here. Instead, I’m going to go a little deeper into some powerful features that can be used with Web API.

Auto-generated Documentation

API documentation is notoriously difficult to keep up to date. After you finish writing or updating a method on the API, you must then go to your documentation and make updates to it that correspond to the changes you made to the API. It’s easy to forget, and it’s hard to find the time. But Web API has the built-in ability to automatically generate help documentation pages for you. To set it up, follow the documentation at http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages.

Read More