Getting started with web services

With Yahoo announcing some pretty cool web services today, it’s a good time to mention that we’re also in the process of adding some super simple web services to 43 Things pretty soon. We’re hoping to debut at the Emerging Technology Conference (in particular, at the Web Services Mashup Tutorial that I’m participating in with Alan Taylor and Cal Henderson).

As with many things, we looked to flickr for inspiration on how to do things right, and also spent a lot of time reading up on the many varied blog APIs. I tried to follow as many of the design principles that came out of work on the Atom API as possible.

A couple lessons learned along the way:

No need for a SOAP API. First of all, almost nobody uses them (85% of people use Amazon’s REST interface over the SOAP, and almost nobody uses flickr’s SOAP and XML-RPC interfaces over the REST interface). I learned the same lesson when I offered SOAP and REST interfaces to All Consuming a few years ago. Second of all, we can always build alternative interfaces later. Therefore, the first version of web services that we’re offering are REST-based.

Make it easy to get an API Key. We’re requiring people to get an API Key before they start using the services so can limit access to people who abuse the system. But it’ll be easy for anyone with a 43 Things account to get a key (or three), and they’ll be approved by default. At some point it’ll be easy to also display a list of people who are using the service in interesting ways.

Make authentication easy. Many web services don’t require authentication because the methods offered are read-only. In fact, 27 of the 34 methods we’ve implemented so far don’t require authentication. But web services become more interesting when you can use them to write as well as read. For example, posting photos to your flickr account, adding something to your Amazon shopping cart, or adding something to your 43 Things list all require authentication. The Atom API actually has a pretty slick way to authenticate that’s secure and that isn’t so complicated that it becomes impossible to implement. This is proven by the fact that so many people have been able to implement the API in various posting tools during the short time that it’s been out there. So I figured we’d use that same system for our web services. There’s a good article about it here. And for people that don’t want to implement a secure way to authenticate but still want to play around with adding goals and entries to 43 Things, we’re also supporting simply passing usernames and passwords via GET in the URL. That way you can get it working first, and then make it secure later, if you want.

Don’t duplicate work. Because we’re using Ruby on Rails to power our site, all of our code has been abstracted into controllers, models, and views. It only took a few days to build the webservice because it was as simple as writing a single new controller that used all of the same models and then displayed results using XML views rather than HTML views. When we update the way the models works on our website, it’ll also update the way the model works in the web service, without requiring any changes to the API.

All that said, we’ll be offering quite a full set of methods to query everything from goals, people, entries, teams, cities, and tags, and you’ll be able to add goals, remove them, update them, and post entries to them. 34 methods in total so far. I’m really excited about them personally. If anyone is feeling really adventurous and has some extra time on their hands to help test the service before it launches, let us know.