API Design

Recently at Songbird I’ve been working on some guidelines to help us build better APIs. One of the most exciting things we’re hoping to offer users and developers are APIs that give them access to their music and the ability to extend their and others’ music players. Getting these APIs right can be hard and we think we can do better, so we came up with some ideas and we’re trying to get some wider feedback.

Our guidelines come in two parts – general rules that apply across the board, and platform-specific conventions depending on what the specific APIs are based on (Mozilla Extension API vs Web Page JavaScript). Here’s our general guidelines:

  • APIs should be orthogonal and symmetrical
  • Method naming, argument ordering and error handling should be consistent
  • Code that uses the API should read like prose. Words should not be abbreviated. It should be easy to understand code that uses the API without having read the documentation
  • The API should follow the terminology, conventions and idioms of the platform that is is built on
  • Use cases and target developers should be taken into consideration when the API is being designed and documented
  • Developers should be able to continue to use the tools and libraries that they are familiar with when using the API. Their previous development experience should help them learn and understand the API quickly

These are based on research I did – I distilled half a dozen other peoples’ ideas about good API design into ones that we could easily apply to our own work.

The full document fleshes these out a little more, with examples and then goes into platform specific patterns to follow.

If you’re interested, read it and please send your comments.

LUG Radio Live

I’m kind of terrified of public speaking. So I do it as much as possible.

I will be speaking at LUG Radio Live USA 2008 in San Francisco in April. I’m going to be talking about Songbird and the Open Media Web focusing on why what we’re working on over at the nest is especially important to the Linux community. Then I’ll probably show off a few cool things you can do once your digital media platform is open, standards based and extensible.

Here’s what the Lug Radio guys say about their conference:

LugRadio Live USA 2008, the ‘rock-conference’ from the team behind the popular LugRadio podcast, brings the successful and unique formula of the UK LugRadio Live events to The Metreon in San Francisco on the 12th and 13th April 2008. The event is supported extensively by Google and also supported by Dice.

LugRadio Live USA 2008 brings together over 30 speakers across three stages, 30+ exhibitors, a range of BOF sessions, debate panels, lightbulb talk sessions, demos and much more, all wrapped up in the unique event that the UK incarnation has become known for, combining an incredibly loose, social, inclusive, and amusing atmosphere -  you are new to LugRadio Live, it is nothing you will have seen before.

Sounds like fun to me. There will be a huge range of speakers, from kernel hackers like Ben Collins and Kristen Accardi to server folks like MySQL’s Stewart Smith and Samba’s Jeremy Allison. There are library and application developers like Dan Kegal from Wine and Christian Hammond from VMWare.

Apart from me there will be a ton of folks talking about media. David Schleef (of GStreamer and Dirac fame), John Buckman (from Magnatune), Mike Linksvayer (Creative Commons VP) and Aaron Bockover (Banshee hacker) will all be showing me up.

You can see all this and more for just ten dollars on April 12th and 13th at the Metreon in San Francisco. I’m really excited to be part of the conference and really excited to get to hear and meet all the other participants. So if this sounds fun or interesting to you please join me and register.

A simpler mobile OpenID workflow?

Chris Messina posted today about the problems with current OpenID work-flows for mobile users. In spite of a long list of chores I was intending to complete today I had a bit of an experiment with an approach to solving this.

The main problem I wanted to solve was to allow a user to prove their identity without having to enter a password. Most mobile devices lack physical alphanumeric keyboards, and without that it’s very hard to fill out password fields.

Continue reading “A simpler mobile OpenID workflow?”

Moving from Drupal to WordPress for blogging

I really like Drupal quite a lot. It’s powerful and flexible, it’s code is clear and well written and it’s extension mechanism is one of the best I’ve ever seen. All this flexibility tends to distract me from actually writing blog posts. So I’ve moved back to WordPress. If you’re reading this over RSS expect the usual disruption.

I first discovered WordPress late in 2003 from Mark Finlay, an Irish GNOME contributor. On December 24th 2003 he posted:

Everyone go look at WordPress: Seriouslessly sexy blogging Software, looks like it’s gonna kick MT’s ass.

I did, and in the end he was right. Unfortunately he died January 10th 2004. WordPress always reminds me of the three months when we lost Ettore, Chema and Mark.

There were a few scripts around for moving Drupal posts to WordPress but they were all pretty out of date so I took one and updated it. It has a lot of commentary in it. Take a look: drupal-to-wordpress.sql

Songbird 0.3

Last week we release Songbird 0.3. It’s the release I’ve been working on since I joined the Pioneers of the Inevitable in January. There are a whole lot of improvements in there to various parts of the application – the database engine was rewritten to be faster and more extensible, we added tabs to the browser, etc – but that’s not what’s really cool. What’s really cool is the new Web API we’ve developed.

Web pages being displayed in Songbird can (with the user’s permission) interact with pretty much the whole music player. We’re exposing both basic playback controls (what’s the current track, play, pause, next, etc) and access to the music library (see what’s in the library, add to it, etc). This means any music web site can offer a really rich integrated experience. Sites like last.fm or Pandora could offer recommendations without requiring you to download a plugin or desktop application, music stores like Emusic or Amazon.com wouldn’t need to provide a separate desktop applications and could offer the kind of seamless player / web-service integration that only Apple is providing at the moment, and there are a million other possibilities that we haven’t even thought of yet. Right now you can see this at work on The Hype Machine.

Steve and I have been hacking on Greasemonkey, getting it integrated with the bird and writing userscripts that add new functionality to web sites that don’t yet know about Songbird. My most complete hack is one that adds album previews (courtesy of Amazon.com’s music store) to album reviews on Metacritic and Pitchfork. It’s useful and its fun!

PS: yes, it supports your bloody iPod…

Flock 1.0

Flock 1.0 has finally shipped.

Almost two and a half years ago I met up with Bart Decrem for coffee in Palo Alto. He was working with Geoffrey Arone to build a company to write a new browser. Bart wasn’t fully clear on exactly what it would look like or exactly what it would do but he believed that it was important to build a web browser that would break new ground in functionality and experience. He showed me a prototype that showed off two pretty amazing features: really simple bookmarking shared bookmarking and the ability to take pieces of web pages and store them for later reuse. I was excited so I quit my job and joined up.

The first day we were working out of the Bessemer offices in Menlo Park. Beyond Bart, Geoffrey and myself the team included Daryl Houston, Chris Messina, Andy Smith and Anthony Young. Pretty quickly the vision came together. Even though Daryl is the only one of us left at the company the 1.0 product that was just released this week is pretty much what we wanted to build.

In the past couple of years the company has had its ups and downs. There were personality conflicts that were handled pretty poorly (especially by me). There were times of hyper-productivity (I hacked for basically 24 hours straight in a hotel room in Portland to get a feature ready for 0.1) and unproductivity (what did I actually do in the last half of 2006?). But the high-level vision remained clear and nobody working on the product ever doubted that what we were doing was important.

How I set up gitweb

There don’t seem to be any straight-forward documents on how to set up gitweb, the web interface to git repositories. Or at least I couldn’t find any. After failing to get it working a couple of times and then succeeding a couple of times in different ways here’s the recipe I came up with to get what you can see on http://git.ianloic.com/. What I have there is a bunch of git trees I’m following or working on. Perhaps not a bunch, but at least a few.

What you need:

  • a recent git installed
  • Apache
  • the gitweb files (from your git distribution) somewhere in your web tree

Gitweb comes as part of recent git distributions in a gitweb/ directory. This needs to be accessible from the web. I just have a git checkout in my web area and use that. When you build git you can supply all kinds of defaults that are applied when gitweb.perl is transformed into gitweb.cgi. Compile-time configuration and since you can override all that in a config file I prefer to just use gitweb.perl directly. My config file gitweb-config.pl looks like this:

# where's the git binary?
$GIT = "/home/yakk/bin/git";
# where's our projects?
$projectroot = "/home/yakk/git.ianloic.com";
# what do we call our projects in the ui?
$home_link_str = "projects";
# where are the files we need for web display?
@stylesheets = ("/git/gitweb/gitweb.css");
$logo = "/git/gitweb/git-logo.png";
$favicon = "/git/gitweb/git-favicon.png";
# what do we call this site
$site_name = "Ian's git trees";
# these variables should be empty
$site_header = "";
$home_text = "";
$site_footer = "";
$projects_list = "";
$export_ok = "";
$strict_export = "";

Most of that should be fairly straight-forward. $GIT and $projectroot are local filesystem paths for the git binary and the directory that contains your git trees respectively. @stylesheets, $logo and $favicon are URLs. In my case I just use relative URLs. You can customize most of the other variables to tweak the text to display. We have values for all these because gitweb.perl contains junk defaults that need to be cleared.

I wrote a little wrapper CGI, invoke-gitweb.cgi to invoke gitweb.perl with an environment variable to tell it to load gitweb-config.pl:

GITWEB_CONFIG=gitweb-config.pl exec perl git/gitweb/gitweb.perl

Drop gitweb-config.pl and invoke-gitweb.cgi into the directory that contains your git trees. Make invoke-gitweb.cgi executable and make sure your Apache knows to execute *.cgi as cgi scripts.

If you load invoke-gitweb.cgi in your browser you should see gitweb in action! But your URLs are stupid.

Let’s fix that with a .htaccess file:

RewriteEngine on
RewriteRule ^$ /invoke-gitweb.cgi
RewriteRule ^([?].*)$ /invoke-gitweb.cgi$1

This will make any requests for just the directory invoke gitweb and any requests starting with ? invoke gitweb with those arguments. It works pretty well for me.

Installing Ruby Gems in your home directory

NOTE: Updated for RubyGems 1.3.7

I’ve been playing with Ruby in my cheap shared hosting provider. They don’t include everything I need so I had to install Ruby Gems in my home directory. The instructions don’t work. So here’s what I did…

First set up environment variables to tell Ruby and Gems where to find stuff:

export GEM_HOME=$HOME/lib/ruby/gems/1.8
export RUBYLIB=$HOME/lib/ruby:$HOME/lib/site_ruby/1.8

Download and unpack the Gems source (this is the version I downloaded, you should grab the latest:

wget http://rubyforge.org/frs/download.php/70696/rubygems-1.3.7.tgz
tar xzvf rubygems-1.3.7.tgz
cd rubygems-1.3.7

Run the setup.rb script with the right arguments to install into your home directory:

ruby setup.rb all --prefix=$HOME
ln -s $HOME/bin/gem1.8 $HOME/bin/gem

This will install the gem command into $HOME/bin and the Gems source into $HOME/lib/site_ruby. Gems will be installed into $HOME/lib/ruby/gems/1.8. You should add $HOME/bin to your path. If you want to install it somewhere else replace $HOME with the prefix you’d like to use.

Inbox Diet

Anyone who has lived with me or worked closely with me knows that I have a lot of trouble staying organized and a lot of trouble keeping on top of my email. Typically my inbox grows to a couple of thousand messages and then I “archive” it and start again. This happens every couple of years.

When I receive email I either discard it immediately, reply if it will only take a few moments, or if its important and will take some time to deal with I leave it there to be dealt with later. This almost never happens, my inbox grows, my family wonders why I never respond to my emails, my coworkers form the opinion that I’m unreliable, my wife sick of people emailing her when they want to get my attention.

Last week I came up with a great idea. I’m going to put my inbox on a diet. Every day my inbox must shrink by at least 25 items. I estimated that I should be able to get through the 700 or so emails in a month if I can keep up the pace.

Being a nerd, the first thing I did was make a spreadsheet. For each day it tracks my goal inbox size and how I’m doing. I have ups and downs but I’m making solid progress towards zero. There’s even a chart:

As I’m going I’m also building the habit of processing email as it arrives. I can’t afford not to. I know that I’ll fall off the wagon again and I’ll let my inbox get out of control, but I think I’ve got a strategy for recovering.

Mozilla’s missed opportunities

In the past couple of months Mozilla Corporation has sought to narrow its scope. First there was the announcement that at least for the next year and a half or so the focus of platform development will be on developing the Firefox browser as the platform. This primarily means no standalone XULRunner. And since being standalone was kind of the whole point. Now there’s the announcement that they’re dropping Thunderbird because they think it’s a distraction from building their web browser.

When I look at this graph from Janco Associates I see Firefox’s market share’s growth slowing:

After all, how many people are going to download and install a new web browser. How many people really care enough? How many distribution channels can you find with just a web browser? Mozilla Corporation’s closed minded attitude to XULRunner as a platform and non-browser application might limit the spread of Free Software internet client software.

If we had set of application that could all run against a shared XULRunner runtime it would be easy and cheap to piggy-back them on each other. If a user downloaded Songbird so that they could listen to MP3 blogs on their phone it would be easy to offer them Firefox as a browser alternative, even if they hadn’t been interested in downloading and installing a replacement for Safari or Internet Explorer. If an ISP wanted to bundle Thunderbird to make it easier for their users to access email it would be cheap and easy for them to also offer Firefox because on top of any other XULRunner application Firefox is a small download.

This kind of bundling is often done by the bad guys. If you install Apple’s Quicktime codecs on Windows every update will trigger an iTunes install, even if you haven’t installed iTunes. I’m sure they’ll do the same thing for Safari on Windows. I’m not sure what iTunes’ market share on Windows is but it seems to be significant. If all those users suddenly have Safari installed that could potentially cause a big shake-up in browser market share.

We’re not trying to lock users into proprietary software and proprietary services. We’re trying to show them the potential of free software and open standards to make their lives better. We have the opportunity to do this better by embracing our platform and our ecosystem of applications, but the people holding the purse strings in the community are taking an overly conservative approach. I hope it doesn’t cost us victory and our users freedom.