APIs and Support
Zach Waugh •
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.
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.