Saturday, September 22, 2007

API Design - A Lesson Learned

In one of my older posts, I mentioned that I watched an excellent video of Joshua Bloch's presentation on API design.

Joshua mentioned that these days, developers are API designers and often don't even realize that. It's very easy to create a bad API when you don't realize that you're actually creating an API. And that's exactly what happened to me this week.

One of the new features for SunWikis, we released with v1.0.6, was a macro for embedding YouTube and Google videos. A simple features implemented via Confluence's user macros - it was so simple that I actually managed to make it more complicated than it needed to be. All of that just because I wasn't aware of all the options that Confluence had to offer.

My original macro sytax for this feature was:
{video:youtube}<insert the youtube id here>{video}

Only later this week I realized that I could have made the syntax simpler by creating a user macro without a body. The syntax of the video macro without body looks like this:
{video:youtube|<insert the youtube id here>}

This makes the macro code shorter, and as my friend J commented, it helps to make the macro syntax look less like an ugly version of XML.

Compare the old and the new code used to embed our promo video:
The second one is obviously shorter and a bit simpler.

I was lucky enough that I realized this soon enough to be able to fix it before it started to be used at So yesterday I changed the macro code, updated the documentation and fixed all the few pages that already were using the old clunky syntax.

This made me realize that Joshua missed one point in his presentation:

Be more than familiar with the language, protocol or libraries you use to create the API.

In the Java language this means use all the nice features that can make the lives of your users easier (e.g. annotations, generics, ..). In Ruby there are plenty of great idioms one can follow, and the same applies to Confluence's user macros - learn how they work, what they can do, and how you can leverage that.

Lesson learned! Next time I'll think twice and read more docs before I design any API.

No comments: