Shortwave

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.

Examples

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.
HTTP caching
in-built request throttling

Contributions

Contributions are welcome. Source is on github at github.com/knaveofdiamonds/shortwave

Dependencies & Credits

Shortwave depends on the following gems:

Nokogiri
Restclient