Making Your Webservice More Developer Friendly

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:

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.

Dev Accounts

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

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.

-Alex

If you enjoyed this post, please consider to leave a comment or subscribe to the feed and get future articles delivered to your feed reader.

Comments

Of course there’s a Haskell flickr library,

http://hackage.haskell.org/cgi-bin/hackage-scripts/package/flickr

As well as libraries for many other web services (openid, gravatars, twitter, mediawiki…) All on http://hackage.haskell.org

Enjoy!

Ha! I was more trying to emphasize that the web service doesn’t have to release 1st-party libraries in every conceivable language, but that they should release for the major, mainstream ones.

However, I’m not the least bit surprised by this. Flickr would probably be interested, too, if you want to give them a shout:P

[...] 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 [...]

Thanks Alex for this great post. As somebody who only plays around with development now and again, the more that APIs can be built in a consistent manner so that the likes of myself can easily pick them up and do something useful with them the better. The Twitter API I found to be great in terms of simplicity and being well documented.

[...] Making Your Webservice More Developer Friendly | Calling Shotgun 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. (tags: api development) [...]

Alex thanks for writing the article. When we released the API in Oct 2006 our intention was to make it full scale API, but based on where the direction of the product was heading we decided not to invest further into the service. Just to let you know we sunset the AOL Pictures product and API on 12/31/2008. We would be more than happy to talk to you on the other services and API’s we offer on dev.aol.com. You have my contact details. Please keep publishing articles like this so we can improve on our service.

Awesome post Alex (de man), thank you for sharing your experience, I know this post will come in handy, I’ll let you know when I release an API in the future, maybe you could be my biggest crit?

Like your style man, like your title.. “API Documentation: People actually read it”, hehe.

Thanks again for helping me help you. ; )

TM

Great list of important tips for web APIs. I raised this issue on the very same day as you curiously (see link). Thank you for sharing.

[...] Making Your Webservice More Developer Friendly | Calling Shotgun 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. (tags: api development) [...]

I’m new to developing my own Open API for a Web App though not new to development in general.
I’ve a few questions that I seem to run around in circles with and never get anywhere:
1) What is a good model for developing a robust open web API that is also secure?
2) Do sites usually use their own API for the site or is there a better way?
3) What is the REAL difference between SOAP, REST and XML-RPC.

Currently I have an XML-RPC implementation that is NOT secure. I’m wondering if there is a way to secure it and to create an API using XML-RPC. Or even if that is possible. I’ve used Flickr’s api before…what are they doing?

Thanks,
D

[...] a great post by Alex Lucas at CallingShotgun.net about what companies can do to make their API’s more [...]

Hi Migrate,
Just hope you can help me, I have a stack of pics on flickeron the link above,I have used your method to download and did get back one folder of pics, then the download stopped and said that that was all the pics there and there are no more ??
There are still over 3,500 left on flickr can you help me please ?
Regards
Ron

http://www.flickr.com/photos/rupet204/

5…

A full-fledged woman finally completed. The gods for her to wear clothes, wearing a rabbit hat, items with beads, charming as the bride. Hermes ideas, said: “Let this woman Pandora (Pandora) it is the gift of the gods gave man.” Gods are in favor of …

Aw, this was a very nice post. In idea I would like to put in writing like this moreover � taking time and precise effort to make an excellent article however what can I say I procrastinate alot and under no circumstances appear to get one thing done.

There are definitely a variety of details like that to take into consideration. That may be a great point to bring up. I supply the thoughts above as general inspiration but clearly there are questions like the one you bring up where the most important thing can be working in trustworthy good faith. I don?t know if greatest practices have emerged around things like that, but I am positive that your job is clearly identified as a fair game. Both boys and girls feel the impact of just a moment�s pleasure, for the rest of their lives.

Hey! I simply want to give an enormous thumbs up for the good information you might have right here on this post. I shall be coming again to your weblog for extra soon.

This website is mostly a walk-by way of for all the information you needed about this and didn�t know who to ask. Glimpse here, and you�ll undoubtedly discover it.

First time visit here and have your great report. May I’ve a copy of the guide?

I found your weblog web site on google and test just a few of your early posts. Proceed to maintain up the superb operate. I simply extra up your RSS feed to my MSN Information Reader. Searching for ahead to studying extra from you in a while!

Whats up! I just want to give a huge thumbs up for the good information you might have here on this post. I can be coming back to your blog for more soon.

It�s arduous to find knowledgeable people on this topic, but you sound like you recognize what you�re talking about! Thanks

Nice post. I be taught something more difficult on completely different blogs everyday. It can at all times be stimulating to read content from other writers and follow just a little something from their store. I�d choose to use some with the content on my blog whether you don�t mind. Natually I�ll provide you with a link on your internet blog. Thanks for sharing.

Leave a comment