You’ve done it. You have written the coolest, fanciest utility ever and you want to unleash it on the world. You throw it up on CodePlex or SourceForge and eagerly await the praise from developers all over the world for such a cool piece of software. Ten minutes later you get your first comment: “This is really cool but I need to integrate it with my other utility, do you have an API?”
You should have seen this coming. It’s a cardinal rule. Developers ALWAYS want to extend stuff, or use it in a way that you might not have anticipated. An API allows your product to be integrated with other products, and makes any software package that much more valuable. Let’s look at a bug tracker for example. There are all sorts of opportunities for an API with something like this. What if you want to trap unhandled exceptions in your application and create bugs with them automatically? What if you want to take any bugs that are assigned to you and have them show up in your task list? Those are perfect examples of why an API is useful.
OK. So we know we need an API, the question is how do we do it? What do we need to consider? I’m going to assume that our API will be web based, meaning that we will access it through port 80. The age old debate seems to be Representational State Transer (REST) vs. Simple Object Access Protocol (SOAP). I’m not going to incite a flame war by saying one is definitely better than the other, there are great examples of each. Off the top of my head, I’d say Flickr is an outstanding example of a REST API, while Amazon is a great example of a SOAP API.
DISCLAIMER: It was correctly pointed out to me that Flickr’s API is not a good example of a REST API, and my example API in this article is actually more like RPC than REST.
Basically, our API will take a request, and return an XML string with the response. The first thing we need to do in order to make that happen is to write our own HttpHandler. To do this, you need to create a class that implements the IHttpHandler interface in the System.Web namespace. Your class should look something like this after implementing this interface:
I’ll start with the IsReusable property. This just indicates that a single instance of our handler can handle multiple concurrent requests. What does this mean to you? For your handler to be reusable, it must be thread safe. The ProcessRequest function does all the work for our handler, taking the HttpContext as a parameter. To keep this example manageable, we will only create one method for our API, we’ll call it LoadPeople. Since our API will be returning data in an XML format, we need to decide what the format of our XML should look like. Each of our people records will have a first name and a last name, so our XML could look like this:
I’m not going to go into a lot of detail about this part, I’ll just sum it up by saying that my website project has it’s assembly name set to RestAPI in the properties, and our handler’s classname is TestHandler. You can get more information on how to set these up here or here. I chose .ashx as my extension arbitrarily, so use whatever extension you like.
Lastly, we need to write the request processing function of our handler. I threw together a quick example, and mine ended up looking like this:
When you are sending output through the API, you can use the Response object in the HttpContext that is passed into the ProcessRequest function. I used the XMLTextWriter class for my output, and just sent the output to the OutputStream of the Response object, as seen on lines 44 and 69 above. Everything should be fairly self explanatory above….I just put together a dummy collection to return to the user. This sample API relies on the function being requested being called through the URL, so I also included a way to tell the user that they requested an invalid method.
One thing that I didn’t touch on with this example is parameters. You could fairly easily have full parameter support by just passing them through the querystring. For example, you could add an AddPerson function to our sample API and call it like this: http://www.oursite.com/API/AddPerson.ashx?firstName=Jimmy&lastName=Jones. We would just have to be sure to error check our parameters for the function, etc.
That’s all their is to it, an API in just a few steps!