Shortwave aims to be a complete API wrapper for the Last.fm web service.
Shortwave is split into two: the Facade, which provides a low-level thin wrapper around the remote api, and the Model (which uses the Facade) which provides a more OO view of the api. It would be possible to build your own api on top of the Facade if you don't like the Model api provided - the two are fairly separate. See the docs for the Facade model if you want to use it directly.
Shortwave is currently pre-alpha. This means both the API and dependencies may change quite a bit over forthcoming releases.
Advantages over other libraries.
Shortwave aims to be complete. The facade is autogenerated from the Last.fm api documentation so as the last.fm api evolves it should be possible to keep it in sync relatively easily
No enforced opinions - the Facade is a very thin layer, so you can use it directly and treat the returned XML as you please.
Supports all 3 authentication types Last.fm provide.
Doesn't rely on static/class properties for things like session keys. This means you can build applications which have multiple users signed in.
You need to create a session using one of the Authentication mechanisms:
session = Shortwave::Authentication::Mobile.new("your_api_key", "your_app_secret") session.authenticate("user","password")
See the documentation for each of the Session types for how to authenticate for your platform. Once you have a session, you can get model objects from it:
session.artist.search("The feelies") # => returns a list of Artists session.user.logged_in_user # => the current user session.tag.popular # => the most popular tags
See the Provider docs for more details of how you can access models. Models have attributes and links to other models.
venue = session.venue.search("Koko").first venue.city # => "London" venue.events # => "list of events" venue.events.first.artist # => an Artist
Current limiations & TODOs
Paged methods only provide the first page of results when accessed through the model. The goal is to make it transparent that you may have to make n remote calls to get a certain number of results. You can, of course, access arbitrary numbers of results through the Facade methods.
Not all attributes will be populated on Models when accessed from different method calls. This is down to the set of data Last.fm returns. The goal is to have missing attributes be populated as needed by further api calls.
Might be nice to have Playlists use another ruby XSPF library for more functionality.
Radio tuning not done yet.
in-built request throttling
Contributions are welcome. Source is on github at github.com/knaveofdiamonds/shortwave
Dependencies & Credits
Shortwave depends on the following gems:
Shortwave also includes a version of HappyMapper (under vendor) copyright John Nunemaker, hacked about to work directly with Nokogiri documents and fix some bugs. See vendor/happymapper/License for details.
Copyright © 2009 Roland Swingler. See LICENSE for details.