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:

{video:youtube}tpR_6y-OoRc{video}
{video:youtube|tpR_6y-OoRc}

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 wikis.sun.com. 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.

Are You a Right Clicka or an iBook Flippa?

This video made me laugh hard today:

SunWikis v1.0.6 Released - Embedded Videos & Google Analytics

Yet another update for our wikis.sun.com, bringing exciting new features, was rolled out today!

     

Just to mention a few:

• Support for Google Analytics - space admins can now track activity in their space on their own
• Support for space logos and user avatars
• New Plugin: Create Page Macro
• Support for embedding YouTube and Google videos

Detailed release notes, with instructions on how to use the new features are available here

Ohh.. and did I mention that we have a new lol zuke for our maintenance page? :)

What's next? I want to finish up the Google Analytics support so that it is fully configurable from the Space Admin interface. And most likely we'll also open up the remote API so that SunWikis can be used in other than traditional ways. Stay tuned!

Solution for the Java Web Start Not Launching Problem

A couple months ago I noticed that I couldn't launch any Java Web Start application from my browser (by downloading and launching a *.jnlp file). When I try to launch an app, the Java Web Start logo appeared and after 20-30 seconds it went away and that was it. How frustrating!



I struggled for a long time, but then I found a solution posted on a site.

All you need to do is to delete the cache:

rm ~/Library/Caches/Java/deployment.properties

Today the problem re-appeared, but armed with this knowledge, I fixed it in a second.

I have a feeling that this problem is somehow related to the preview version of JDK6 that I installed on my Mac. Apple, where is that darn JDK6 final?!?!? Unfortunately, even when Apple JDK6 is out, it most likely won't be any good for my Mac OSX 10.4 Tiger.

Is Blockbuster Playing Fair?

I just got an email from Blockbuster telling me that they are canceling my plan and I'll either get less for the same amount of money or I have to pay more to retain the current services.

Blockbuster launched their Total Access program approximately a year ago. With this program online subscribers could return DVDs to traditional brick-and-mortar stores, and exchange them for free in-store rentals.

Now Blockbuster is modifying this program to limit the number of DVDs one can rent. I understand that some can be abusing the system and renting many many many DVDs for little money. But for some reason, I have a feeling that all of this was just about hurting Netflix, their only real competitors, by taking advantage of their store network. And now when Netflix is bleeding, it's time to stop giving out DVDs for free and start cashing in. Taking advantage of assets to temporarily blind customers and not-so-temporarily hurt the competition, doesn't seem to be fair to me.

Now is the time for Netflix to fight back, down and dirty. Maybe by adding the one category into their catalog that Blockbuster won't touch with a ten-foot pole? Yes, I'm talking about adult movies. :))

API Design and JSR 310 Replacing Java Date and Calendar Classes

It seems that today I'm stumbling upon a lot of interesting stuff.

While coding stuff for tomorrow's wikis.sun.com release, I watched this pretty good talk in which Joshua Bloch, once again, excellently addresses the issues and pitfalls of API design:



During the talk, Joshua makes an interesting comment. A JSR was created earlier this year, that is supposed to *finally* replace the crippled Date and Calendar classes in JDK. JSR 310: Date and Time API is lead by folks responsible for Joda Time library, that's a great sign! The request well captures current problems and needs, and I can't wait to see it implemented as a part of JDK.

NetBeans IDE 6.0 Beta 1 is Out!

While searching for a nightly build of NetBeans I noticed that NB6 Beta 1 is out. Great!

I'm looking forward to using the new version. After spending the last couple of weeks (or months?) developing in NB6M10, I can't wait to see what this release brings.

The first thing that stuck me though is the lack of "drag&drop" installation on MacOS which was replaced with "pkg-style" installer. I liked the drag&drop installation better - it's more mac-ish. I hope the surprises that will follow will only be pleasant.

Thanks, NB guys!

Download link: http://bits.netbeans.org/download/6.0/milestones/latest/

TinyURLs are Evil!

Thanks to Linda and J, I got introduced to Twitter and after a couple months of hesitation I created my own account.

Shortly after I started tweeting, I noticed that Twitter uses the TinyURL.com service to cut down the length of their tweets (twitter messages) to minimum.

Seeing all these tinyurls all day long provoked me to post a list of problems that TinyURL and other similar centralized url hiding services bring:

1. TinyURL doesn't have any semantics: Rails, wikis, REST and other new technologies are striving for human readable URL. When these urls are seen posted somewhere, one gets an idea of what to expect and can easily determine if he's interested in viewing the page behind the url based on the domain name, keywords in the url or file type (in case of downloadable files). Compare: http://en.wikipedia.org/wiki/TinyURL to http://tinyurl.com/dmsfm. Both point to the same page, but while the original url sets the expectation (almost everyone knows what can be found on wikipedia, and the keywords "TinyURL" offers even more specifics), the TinyURL (short url) has no meaning for anyone until it is opened in the browser.
2. TinyURLs can be misused for XSS and XSRF attacks: Would you click on a link in an email from a friend that looks like http://mybank.com/sendmoney?amount=50000&to=badguy and how about http://tinyurl.com/2nwz9q ? This example is a bit exaggerated, but who knows, it might not be far from reality. :-/ The fact is that TinyURLs are being misused for obfuscating urls with exploits.
3. TinyURL and user privacy concerns: Since every TinyURL request is handled via TinyURL infrastructure, all the information about who, when, from which site, and from which computer clicked on a TinyURL link.
4. TinyURL messes up search engine logic: Many, if not all, top search engines rely on analyzing which site links to which and use this information to determine which site is popular. What happens when many urls point to other sites via TinyURLs? You can guess which site (hint) gets all the extra points and is considered to be popular.
5. TinyURL messes up web site statistics: If you track activity on your website via services like Google Analytics or Omniture SiteCatalyst, you often want to know where your traffic is coming from. Well, if someone points to your site via a TinyURL, all you'll see is that the traffic is coming from a TinyURL.com site. The reason for this is that when coming to a site via a TinyURL, the referer is always set to TinyURL.com

Enough ramblings. What can you do to protect yourself from the threat of the dark side? Stop using TinyURL.com and other similar services. :)

Other than that, there is not much you can do about most of the problems mentioned above, except for the XSS & XSRF problem: If you get a TinyURL, you can preview it by modifying the url from http://tinyurl.com/dmsfm to http://preview.tinyurl.com/dmsfm. This will show you the destination URL before you are redirected there. If you want this to happen automatically every time you click on a TinyURL, you can save this preference as cookie that will trigger the preview behavior automatically.

Developers that want to cut down on the amount of rendered text should consider rendering urls as en.wikipedia.org/... or just as [url] instead of using the evil TinyURL service. This approach however doesn't work for e.g. printed media, sms.

Don't get me wrong, I'm not saying that the TinyURL service was created with evil intentions, I just think that it was an attempt to solve a common problem, that took a wrong route. Interestingly the Wikipedia page dedicated to TinyURL contains more content about issues related to TinyURL than anything else, I guess it proves my points. :)

Just to confuse everyone even more, there is a few cases when using TinyURL-like services is recommended, I'll come back to these in one of my future posts.