Almost every web app these days has an API. They have been integral in helping many apps, especially Twitter, grow from a service to a platform. Twitter just recently announced they surpassed an incredible 1 million registered apps. Most companies would kill to have that many users. All the APIs out there now are great, and have enabled all kinds of amazing apps to be created, but there’s one problem: support. Even though many APIs are responsible for the popularity of a service, they’re often in no-man’s land as far as support goes.

I’ve been dealing with this a bit myself recently. I’m currently working on a Campfire client for Mac OS X called Flint. The documentation isn’t great, and I’ve had a few questions as well as found bugs with no where to go for answers/report them. 37Signals only provides one place to go for API support, and that’s a Google group where most questions never receive a response. After waiting a few weeks, I’ve had to contact their main support to report bugs. It’s a very frustrating experience when you’re trying to create an app, and your hands are tied.

This is certainly not unique to 37signals, and I don’t mean to call them out specifically, but it’s just my most recent experience. And I understand that they’re in a tough position. They make money from paying customers, and any time they spend supporting non-paying API developers, is time they’re taking away from customers that depend on their products and require help. I can’t imagine how completely overrun their support systems would be if any developer messing around with the API could contact them to ask a simple question.

On the other hand, people that use the apps and services created with the API are customers. Every app that integrates with their platform increases the value of their product. It directly benefits them to have a useful, reliable API. Twitter realized the value of this and just rolled out an all new developer site. But most APIs are treated as an unsupported, proceed at your own risk extra. It’s a shame that many companies that have APIs don’t see the full value of it.

My point is don’t offer an API if you don’t have plans of supporting it, and I mean really supporting it. It doesn’t have to be your premier, call us any time of day support, but there has to be somewhere for developers to go. There are a few things you can do if you really want to create a healthy developer ecosystem.

Documentation

This should go without saying, but we need accurate, thorough, and up-to-date documentation. It’s amazing how many docs fail on at least one of those. The better the documentation, with the more examples and client libraries you provide, the less we’ll need to bother you. Provide complete documentation of every method, every type of response, and every type of error. Give us some guidance on usage too, and document the things that fall outside of method calls, like “users will be kicked out of the room for inactivity every N minutes unless X is performed”.

Issue tracker

If there is a problem, there has to be somewhere to send it. We need a issue tracker where we can file bugs and see open issues and their status. We need to know whether we’re just doing something stupid, or there is a known bug that’s going to be fixed in the next release. Or maybe it’s something that’s been covered before and isn’t going to be fixed.

Forums

If you have forums, we’ll most likely help each other out, but we need an official representative (preferably an actual developer of the API) to monitor and respond to user posts. Just assign a developer to check out and respond to messages a few times a week. I think most developers will go out of their way to improve documentation and fix bugs if they’re the ones that have to keep dealing with the same recurring question.

Email

This shouldn’t be necessary if the docs are great, and the forums are actively monitored, but give us some sort of last resort to directly contact someone. The majority of people are respectful and will realize not to abuse this, but things come up, and sometimes there are pressing needs beyond the support forum.

If you want developers to build for your platform, treat them as first-class citizens, and give them the tools and support they need to make great apps. If you don’t want that, then don’t provide a public API.

I received quite a few comments on my How to use JSON in Cocoa/Objective-C post with some confusion related to the response from API calls. I thought it might help to show an example of the steps you’d take if you wanted to integrate the Twitter public timeline (or any other API) into your app or site. For doing any sort of HTTP/API request analysis, I first turn to HTTP Client.

HTTP Client by Todd Ditchendorf (creator of Fluid) has quickly become an indispensable tool for me when writing code that interacts with RESTful API web services. For building the request, HTTP Client allows to you use any of the HTTP verbs (GET, POST, PUT, DELETE, etc) as well as setting custom headers, body, and use basic authentication. The response view will show you all the headers and the raw request body. If you’re still using cURL, it’s time for an upgrade.

Typically, the biggest problem with using APIs is poor documentation. Even when the request docs are pretty good, the response docs often fall short. Either they don’t document the response at all, only document a portion of it, or only show it in one format. So my first step in implementing some API code is looking at the docs, and seeing how the request is formed. Twitter has a simple API, and pretty good documentation, so it’s easy to figure out how to get the public timeline as JSON on this page http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses-public_timeline. The URL for this request is just “http://twitter.com/statuses/public_timeline.json” and the HTTP method is “GET”.

The next step is firing up HTTP Client and making the request to see what it looks like (see screenshot to the right). Twitter is a simple case where you shouldn’t have trouble, but for more complex APIs with a lot of options (like the Google Analytics API), it might take a bit of trial and error to get the exact data you’re after. It’s much quicker to iterate in HTTP Client to get your requests working right than to try to do so in code. This will allow you to get your request formatted correctly, and find any problems, like authentication errors or unexpected redirects, right away.

Once I have the correct request, the final step is to look at the structure of the response so I know how to parse it. I prefer to use JSON whenever possible, so it’s mostly seeing what is an array, what is an object, and how things are nested. HTTP Client seems to do a pretty good job with syntax highlighting of XML and HTML responses that make them nice and readable, but unfortunately not with JSON. A quick solution is to copy the response, paste it into TextMate, set the document as JSON, and use JSON-> Reformat Document. (You’ll need the JSON bundle to do that) That will give you a nice, readable view of the structure.

In the screenshot to the right, you can see the JSON response of the public Twitter timeline. By looking at the response, I can immediately see first off, that the main structure is an array. The elements of the array are status objects and each status object contains a user object. Without looking at the formatted response first, it might not be obvious that the user is a nested object of the status.

That’s it. Now I know exactly how the request and response are formatted, and I can easily write the implementation code without any surprises. It seems like a bit of work, but it’s all of 5 minutes when you’re familiar with the process, and is much faster than trying to locate a bug in code that’s really due to a malformed request or unexpected response structure.