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

Migratr 1.05 – Migratr adds Photobucket Support!

migratrI know it’s been a while since I released a new version of migratr, but since I had a couple of days off post-christmas, I had some free time to finish up some bugfixes, aesthetic tweaks, and photobucket support that I’ve been working on for a while.

Oh snap! What’s that? Yeah, you read correctly. Migratr [finally] has Photobucket support! So for those of you itching to give Photobucket a shot, or for those of you with a few hundred photos wrapped up in photobucket and wanting to give another service a shot, now’s your chance. Go! Play! You’re free now. It’s all okay.

Also, I outsourced some logo development for Migratr. The picture you see at the top of this post is what you’ll see from now on as the application icon in the start-menu and/or desktop shortcuts.

Anyway, as always, rock the big download button to download the new, swanky version.

Download Migratr Version 1.06

Downloaded a total of 131726 times

Migratr Reviewed on PCWorld.com!

Hello there friends! A bit of good news, Migratr got a very nice review on the pcworld.com website! Check it out here.

Sorry for the lack of updates lately. I’ve been plugging away, but sometimes it’s hard to get to a stopping point where I can say “this is ready for release”. Will prob. have something up before the end of the year. And, as a sidenote / friendly reminder, AOL Pictures closes on Dec. 31, so all you who use that service have just under a month to get your pictures and get out:)

-Alex

Killing the Fencepost in C#: A handy code snippet

A short while ago, a buddy was saying how learning Lisp had made him start thinking of everything in terms of map/reduce. As an example he gave me an example of a recent python snippet he’d written.

return reduce(lambda l, r: l + seperator + r, (str(s) for s in values))

While I’m not going to claim to be some sort of industry expert on the subject, and there are probably wikipedia entries and blog posts and Knuthian essays I haven’t read on the subject, this is pretty easily the most simple, elegant fencepost solution I’ve ever seen in my life. There are no special cases, boundary case handling, seeding (ie, initialize the final string to the first element, then start the loop at the second). It’s flexible, straightforward, relatively easy to understand to someone with a sufficient familiarity of lambdas. It just does its thing and disappears.

And then it occurred to me, since lambdas had been brought to c#, that this was suddenly within my power to accomplish as well.

I had certain goals in mind, as the snippet provided to me had set a serious benchmark. I wanted it to be as general and flexible as possible- It shouldn’t take only arrays, or only lists. You should be able to throw any sort of collection at it that you want. You also shouldn’t be restricted to only sending it Strings- Might as well make it possible to send it a collection of numbers, or people, or pretty much anything you want. This was more of a “hey, while we’re at it.” Feature creep, I know, I know. But it’s my exercise, and I’ll rock it as I see fit:D

Next, I wanted it to be as simple, elegant, and straightforward as possible. To me, the most significant thing about the snippet was, as stated above, that there was no special case code, and no seeding. You can develop an inferiority complex trying to make c# code as elegant as python code, because c# is a more verbose language. It just requires you to be much more explicit about everything than python does- Especially when it comes to LINQ and collections. Brackets, parentheses and curly braces everywhere. Still, I felt a degree of elegance was possible, and I was determined to find it. What can I say, I was bored, have had minimal exposure to functional programming, and the idea intrigued me…

Here’s what I came up with.

public static String fencepost(IEnumerable values, String seperator)
{
    IEnumerable<String> strings = values.Cast<Object>().Select(x => x.ToString());
    return strings.Aggregate((x, y) => x + seperator + y);
}

By way of explanation, LINQ is more an attempt at emulating SQL than functional programming. So the rough FP -> .NET corollaries are “Map” -> “Select”, “Reduce” -> “Aggregate”. Also, as a one liner it got way too complex to really be readable, so I split it up into two- The first line creates a typed Enumerable of type String from a typed or untyped collection, for the second line to work with.

I also somewhat bundled up the whole thing as a full method, which you can copy-paste somewhere and call whenever you need it, choosing your seperator token on the fly (comma, period, space, whatever). If, on the other hand, an in-line snippet is more your style, here’s a very straightforward one-liner (that assumes you have a typed collection)

  string seperator = ","; //Or whatever else you want to use
  string result = (String)foo.Aggregate((x, y) => x.ToString() + seperator + y.ToString());

Not quite as zen-like as the python version, but it has it’s own strongly-typed schwerve to it. I consider this “Garage Sale” code- Not really complicated enough to license it, so just copy/paste to your heart’s content. Enjoy:)

-Alex

AOL Abandons 28 Million Potential Pictures Users By The End Of The Year

File this!AOL disappoints yet again! It has 28 million users all over the country and it can’t seem to get its act together. In the last year or so it has launched or talked about launching and then killed off over 50 product and service options, and much of what was touted as being the new wave of innovation for the future of the company has already been discontinued. The rest is following suit like rats fleeing from a sinking ship!

As if AOL hasn’t done enough disappointing things in the past, like getting rid of a number of people who relied on their jobs because the company’s plans for some silly thing it tried to launch didn’t work out right, or badgering people who try to cancel their membership over the phone until they’re nearly in tears, now AOL users who are still loyal to the company (for whatever reason) have something else to contend with.

On July 14th, Kevin Conroy (he’s AOL’s Executive Vice President, for those of you who don’t know), sent out an internal memo saying that AOL Pictures and a few other things – XDrive, BlueString, and MyMobile – were going bye-bye. Just leaving. Why? Simple. And the same reason that any business gets rid of anything – it’s not pulling in the huge sacks full of dollars that the company thought it would back when it launched. It doesn’t seem to matter that a lot of people like this service and use it, or that there are a lot more AOL members who might be enticed to use it in the future if it was marketed to them properly. AOL users would probably be pretty disappointed about the disappearance of their photo site – if they knew.

Conveniently, there is no mention on the actual Website (http://pictures.aol.com/) that the service is shutting down. Not even a hint hidden somewhere in a corner or a little tidbit of info stuck down in all that fine print along the bottom. Instead, the site offers to log you in or sign you up for a free account if you don’t already have one, and invites you to do more with your pictures and check out BlueString (also leaving). You’d think that a site that has a number of users who rely on it and was going away in the very near future would make some mention of it, but hey, that’s just AOL
for ya.

Thankfully, there’s a solution. Here’s what you do. Download Migratr and move your photos away from AOL Pictures, and to something that will still be there for you the next time you want to look at or share those photos. Migratr is a desktop application that’s designed to take photos from one sharing site and put them on another one, along with all the titles, tags and captions you’ve added to them, along with the albums you organized them by. Then the next time AOL gets a bright idea and launches a photo sharing site and then yanks it away just a few short months later, users will be better prepared. In the meantime, AOL users – let’s get those photos moved!

http://www.techcrunch.com/2008/07/24/full-text-of-aol-email-xdrive-aol-pictures-mymobile-and-bluestring-to-shut-down/

http://www.callingshotgun.net/about/migratr