Last week, I gave a short talk at the London Ruby User Group that I titled "Avoiding API Library Antipatterns". It's really about what not to do when you're writing a library to use Flickr's API (although I think there's a lot you can learn for any RESTian service provider from the experience). You can see the slides at Slideshare and there's even a video of the talk at Skills Matter, who hosted the event.
So, what was the gist? Rather than writing lots of boilerplate code to handle every Flickr method, and wrap the returned XML into objects, instead use a generic caller and JSON to eliminate much of your work. If you're able to, use reflection to provide convenience methods. As a result, I use flickraw, because it's the only Ruby library I've seen that does things this way.
One of the weakest points of the talk was that I didn't cover how Flickr's responses don't just change when the API changes. Most methods take the 'extras' parameter, which allows you to flesh out the returned data with additional fields, such as the dates the photo was taken and uploaded. Naive libaries require patching to deal with this; smart ones, handing back the response with minimal changes, don't.
I also shied away from explicitly putting in the slides many of the recent projects I've built, including where? what? when? and the machine tag browser, which rely on using new API methods. If you're stuck behind a poor library, there are cool toys you won't be able to write without fighting it, and software's meant to help, not be hateful.
The talk itself was surprisingly quick to deliver; I blew through the slides in ten minutes, allowing lots of time for questions, which were (thankfully) interesting and insightful. The suggested use of method-missing to provide syntactic sugar (calling flickr.photos.search not flickr.call(flickr.photos.search), for example) if an API doesn't provide reflection (or if the library author wants to avoid having to fetch method information) sticks in my mind as a point that's worth repeating.
This was my first talk to a language-specific group outside Perl, and I'm fairly happy with how it went, so thanks to LRUG for listening and being so welcoming, and I hope readers here also get something out of the talk.