How To Make Your Web Service More Developer Friendly

Not all API providers know how to make developers happy. In fact, although there are now over 1,100 web service APIs available, many of those API providers fail to really understand the needs and motivations of their (potential) developer community. For evidence of how developers can React to both well-run and badly-run API programs, look no further than a very insightful blog post from mashup developer Alexander Lucas on Making Your Webservice More Developer Friendly (Alex is the creator of Migratr a useful desktop mashup that uses APIs from 11 different web services in order to let you migrate photos between different online photo services).

In his detailed post he gives what's clearly real-world, from-the-trenches feedback (and wit) from an experienced mashup developer on what works and what doesn't:

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.

He then goes on to provide an on-the-money "checklist for being developer-friendly":

  • Let developers know your API exists. That is, get the word out. Like list it here on PW:

    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.

    Or other basic options like an "API" or "Developers" link in the footer of your site's navigation 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." [Emphasis added, since this is such a key success factor].

  • Have a developer microsite. Don't let your developer section be just a couple of pages and a reference sheet. Include docs, forums, a blog, Source Code samples, listing of third party apps, etc. Have your staff actively monitor and respond to questions and feedback from the community. And personalize it for the registered developer with 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. Not pulling any punches, Alex argues that there's a vast spectrum of API quality and support. On the one hand he felt "AOL Pictures API was little more than “Look at us, we have an API!” lipservice." But "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."
  • Provide options. This means don't assume that all developers are the same in terms what protocols and data formats they'd like to see you provide. Give em choices. Alex proposes: "At least two of SOAP, JSON, or straight-up REST." Here on ProgrammableWeb we see the savviest API providers offering multiple protocols and/or formats. Why?

    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.

    This is something we've seen here at ProgrammableWeb as an API success factor and something we've addressed at conferences before.

  • Have high quality API documentation. Often API docs feel like an afterthought. Terse at best, inaccurate and out of date at worst. As Alex describes:

    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.

    The key to Alex's point here is that good documentation is an investment that can reap many rewards, including some not immediately obvious financial rewards, like lower ongoing support costs.

    And besides standard, static documentation, other options to consider are rich media for things like videos, screencasts and podcasts. Additionally there's the option of interactive tools like 9+ tools we've covered in the past.

  • Offer special "developer accounts": Here's an interesting idea that Alex proposes that we've not seen much of but has a lot going for it: that is, an account on the service itself with capabilities that are meaningful to the needs of developers. As Alex describes:

    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.

  • Provide more than technical support: This is not one that Alex covered but is worth adding to this list: help your developers help you by giving them business, marketing and other non-technical support. Some of the best API programs (but not enough) will help developers succeed one the code's written through programs like joint marketing, promotion through Solutions Galleries, certification, etc.
  • Look to build community and passion: Another addition to Alex's list is generating developer satisfaction by creating a strong community. This starts with the forums and online support, but smart API providers are taking this further by creating opportunities to meet their developers in-person (and have the developers meet each other face-to-face). This ranges from smaller events like Facebook Developer Garages to annual events like the eBay Developers Conference, Google I/O and Dreamforce. For a precedent, look at the ways in which the folks in Redmond built a substantial developer community on earlier platforms.

A checklist like the one Alex has given should be part of every developer program strategic plan.

And in the end, Alex concludes by pointing-out to API providers why they should listen, and why it's in their own best interest to do so:

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.”

Good advice.

Be sure to read the next Best Practices article: The Twitpocalypse is Near: Will Your Twitter Client Survive?