I’ve been working on Migratr for around a year and a half now, and in that time have added support for 11 different webservices. Sometimes I’ve grabbed third party libraries designed for interacting with those API’s, other times I coded up the service-interaction layer myself, and I’ve gone through SOAP, Rest (via URL munging or XML via post), JSON and in one case, even webscraping. It’s been an immensely educational and rewarding experience, with degrees of difficulty varying from totally easy (23HQ, by copying the flickr API verbatim and changing only URL endpoints, took about an hour including testing) to ridiculously difficult (AOL Pictures might have been more popular if their API was more than lipservice).I can only speak to Photo-related web services, as that would be the area where I have the most experience. But I think most web services “get it” with regards to an API- By publishing an API, and enabling and encouraging developers to interact with your webservice, you’ve effectively given yourself a dev team larger than you could ever hope to afford. Users passionate about your services, with ideas on how to extend and improve it, and the know-how to implement those great ideas. More applications related to your website means more ways for users to interact with it, which means more chance of a “killer feature” written by a user of your service that ends up driving thousands of new users to you, any one of which can be a developer that continues the cycle. It’s an upward spiral. But it takes more than just publishing an API. You have to make your developers WANT to write stuff for your service. Make it easy and enjoyable for them, and remove as many roadblocks and speedbumps as you possibly can so that they can complete their brilliant idea before throwing up their hands in frustration, or slowly, quietly losing motivation amidst a sea of vicious bugs, counter-intuitive behavior and documentation that either looks like it was written by Hemingway or run through babelfish. Given my relative experience in dealing with API’s en masse, I decided to compile a checklist for being developer-friendly. Some of it is necessary. Some of it is more along the lines of “helpful”. Some of it is just wishful thinking. But these steps will help you tenfold.
Let developers know your API exists
Publish a listing for your API on Programmable Web, effectively giving the internet a cheat-sheet for your API- Protocols (soap, json, etc), documentation links, fee information (free non-commercial, pay commercial?), 1st and 3rd party libraries. You’ll get legions of volunteer devs through this site, who might not have even known your service existed. Also, a “developers” link in the footer of your website is like gold. It should link to a page providing the basic information: API Sign-up process, documentation, etc. I don’t want to go trolling through support documentation or chat live with a customer service rep. Just let me hit the ground running.
The developer section of your site should be more than a couple pages. It should be a microsite.
In no particular order, this should include most (if not all) of:
- developer forums
- some of your own developers monitoring and answering questions in the forums
- API documentation
- links to working third-party applications that use your API, or third-party libraries that access it
- API news and updates, blog-style
- a “My Profile” section showing me my own API keys, stored app descriptions and (unusual, but I consider this a bonus) usage statistics.
Don’t half-ass your API
AOL Pictures API was little more than “Look at us, we have an API!” lipservice. There’s no way to programmatically log-in and access private pictures, there’s no way to upload via the API, and the system for returning information about those pictures was unintuitive bordering on useless. The API should be a programmatic reflection of what your web service is capable of. On the complete opposite end of the spectrum from AOL, Flickr has an AMAZINGLY comprehensive API. You can fine-tune not only what data, but how much of it you want returned. You could practically create a flickr clone using the flickr API as a backend. (Disclaimer: Morally and legally, that’s a really bad idea.) Another bonus-points case: Kristopher Tate (of Zooomr fame) once told me that the Zooomr website was a display layer built on top of the API. I’m not asking you to do that, it’s a decision you have to make. But we know for a fact that, in this case, it’s well-tested:D It’s also based off the Flickr API, which means it’s super-easy to modify a Flickr app to make it Zooomr-compatible.Another point, try to provide a few different options in terms of protocol. At least two of SOAP, JSON, or straight-up REST. Recently I came across an API that’s accessed via SOAP, but doesn’t provide a WSDL file. That’s cruel. I mean it, it gives me the distinct impression they dislike me personally:P Seriously, though, different languages a way of making different protocols easier/harder. Giving the option of parsing XML vs JSON, or providing a WSDL file and letting a code generator handle all that for you (a serious perk of client development in .NET) makes your API more language-agnostic and universally accessible. To summarize, the API should be stable, complete, flexible, and not counter-intuitive.
API Documentation: People actually read it.
Again, Flickr comes to mind as a shining example. Every method you call via their API has documented behavior on whether it needs the user to be authenticated, parameters, example of the response sent from the server, and possible error codes. There should be a TOC of methods split up by category (for example: photos, albums, user groups, friend list, authentication) so I can quickly and easily hone in on exactly what I’m looking for. Provide links to every third-party library that someone has written for accessing your service in a particular language.Provide tutorials and walkthroughs, and if a third-party dev writes one too, link to that. Throw in some sample code in a few popular languages (Java, c#, python, ruby, perl) so people know what the code should look like. You don’t have to do this for every method. I’d recommend doing this for the authentication step, as developers will be able to test this without getting anything else right first. The net idea is that I should be able to get rocking with your API as soon as possible in the language of my choice, provided it’s a relatively common language (I don’t expect there to be a “Flickr Haskell Library”, for instance. But I do expect a Java one). Good documentation means your dev forums will be manageable.
I’m a little biased on this one, given that I interact with so many different webservices. But of all the services I use, most have “pro” accounts that I need to be able to test against. Some sites (major props to SmugMug and Zenfolio) comp pro accounts to developers who have written software that interacts with their services, as a matter of practice. Others will give the developer a one-year coupon upon request, while others don’t give us anything at all. Software is going to need testing, and if I run into a free-account limit for uploading data to your webservice while testing my software, I’m either going to have to cough up money for the right to add value to your service, go through the lengthy process of clogging your database with test accounts, or wait a month until I can do more testing. These are all roadblocks. I’m trying to write something your users will appreciate. Please don’t leave me hanging like this!
One thing that I would *like* to see, that I haven’t yet, is a special developer account- Not just a comped pro account, but a user account specific to developers. This account could have behavior specific to testing my software, like
- API-Accessible switch between account types, like “free”,”standard”,”pro”,”super-mega-expensive-awesome-pro-account-of-extreme-justice”, in terms of toggling things like upload/download limitation that vary from account to account, to reproduce errors my users are seeing and test for different errors that might come up
- None of the things I do via the API show up in “Latest activity” bar on front of site. If I’m running tests, it would be good etiquette for me to be able to avoid what could be considered spamming
- 24-hour deletes or auto-rollbacks: If it’s a test account, It’d be nice for me to be able to keep the account empty when I’m done testing, without writing housekeeping code on my end that just deletes everything. This means I’m trying to take up less space on your servers. I’m not saying this should be automatic, just we’d both be happier if I had the option.
Sites that don’t hand out free pro accounts to developers could offer these up instead, and just cripple the accounts in ways that would only matter to an active user: the 24 hour deletes could be mandatory, all data posted on a social site could be kept private and not visible to the community, etc. The main point here is that while I totally dig on the incentives provided by the services whose API’s I interact with, it’s more important that I be able to test my software against theirs, fully and comprehensively.
All this really matters, and so do your developer-users
I know it sounds pretentious and self-important when I say that as a third-party developer, I’m adding value to your service just by coding something against your API, and thus you should make things as easy for me as possible. Like I’m the kind of guy who always types “M$” when I mean Microsoft, or leaves obscure, nerdy references in parentheses followed by “anyone?” (Slashdot/Reddit commenters, anyone?). But I swear I’m not being that guy. I’m basing the idea that I’m adding value (or, in the case that I suck, the idea that someone else is adding value) off of the services I’ve seen flourish, and the ones I’ve seen wither and die.Yahoo Photos and AOL Pictures: Half-assed API (Yahoo’s was even web-only, so you couldn’t write a desktop application for it). Both deadpooled. Imagestation and Epson Photos: No API. Both Deadpooled. Flickr, SmugMug, Zenfolio, Phanfare, PicassaWeb: Comprehensive, well-documented API’s with active developer communities, responsive staff and a wealth of resources for helping you get stuff done. Thriving.
In summation, in the words of Jerry McGuire, “Help me help you.”
Come on. I had to say it. You know I did.