Getting started

News

May 18 2010

Appending consumer_key param to all requests to public resources.

Removing Event model.

19. November 2009

With version 0.4.2 we switched back to the mojodna oauth gem, since the bug was finally fixed. We also had to switch to gemcutter.org to host our gems, since github doesn't support gem building and hosting anymore. By doing that we renamed jwagener-oauth-active-resource to oauth-active-resource.

September 2009

With the soundcloud-ruby-api-wrapper version 0.4.1 we switched from the official (mojodna) oauth gem to pelle oauth gem (0.3.6) because of an everlasting,unfixed bug in the official gem.

Required Gems

Installation

First install all the missing required gems. To install the oauth-active-resource gem you can use: 
$ sudo gem install oauth-active-resource -s http://gemcutter.org
Then install the soundcloud api wrapper gem: 
$ sudo gem install soundcloud-ruby-api-wrapper -s http://gemcutter.org

Setup OAuth things

Look at http://wiki.github.com/soundcloud/api/oauth-example to find out, how you setup your OAuth things.

First steps

Let's start with a simple app. It will find and display the 10 hottest tracks of alltime. You don't need any OAuth authentication to do this. 

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

# Create an anonymous soundcloud client
# if you prefer to work with sandbox-soundcloud.com, replace this with:
# sc_client = Soundcloud.register({:site => "http://api.sandbox-soundcloud.com"})
sc_client = Soundcloud.register

# Find the 10 hottest tracks
hot_tracks = sc_client.Track.find(:all,:params => {:order => 'hotness', :limit => 10})

# and display their titles
p '==the 10 hottest tracks=='
hot_tracks.each do |track|
  p track.title
end
To test authentication you can use this small app, which will dispay the name of the logged in user. 

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

gem 'oauth'
require 'oauth'


# Create a Soundcloud OAuth consumer token object
sc_consumer = Soundcloud.consumer('YOUR_APPLICATION_CONSUMER_TOKEN','YOUR_APPLICATION_CONSUMER_SECRET')

# Create an OAuth access token object
access_token = OAuth::AccessToken.new(sc_consumer, 'YOUR_OAUTH_ACCESS_TOKEN', 'YOUR_OAUTH_ACCESS_SECRET')

# Create an authenticated Soundcloud client, based on the access token
sc_client = Soundcloud.register({:access_token => access_token})

# Get the logged in user 
my_user = sc_client.User.find_me

# Display his full name
p "Hello, my name is #{my_user.full_name}"
Find more examples in these pages: [[Model Events]], [[Model Users]], [[Model Tracks]], [[Model Playlists]], [[Model Comments]].

Sub-resources

The Soundcloud API provides 3 different types of sub-resources:

Nested sub-resources

These are directly embedded in the resource. For example a playlist has a track array. 
playlist.tracks
When saving the original resource, the nested array will be saved as well. 
playlist.tracks << some_track
playlist.save

Separate sub-resources

These are separated from the original resource. Example: A Track has the path "/tracks/[TRACK ID]" This track has a collection of users, which have access to this track, called permissions. These can be accessed via the path "/tracks/[TRACK ID]/permission". In ruby they are accessed like nested resources: 
playlist.permissions
But have to be saved explicitly: 

playlist.permissions << some_user
playlist.permissions.save
playlist.save
A lot of these collections are partials, that means Soundcloud API will not return more than 50 items per request. For example the user famous_dj has 120 fans/followers. famous_dj.fans will only return 50 fans. To get all fans you have to do something like this: 

fans = []
limit = 50
begin 
  some_fans = famous_dj.fans({:offset => fans.length, :limit => limit})
  fans += some_fans
end while some_fans.length >= limit
The array fans now contains all fans/followers of famous_dj.

'Single changeable' separate sub-resources

Some separate collections can't be saved in a bulk request. Instead each item has to be added or removed explicitly. For now this only affects the contacts (followees) and favorites of a user. To add a track to the logged-in users favorites: 
track.add_favorite!
Remove: 
track.remove_favorite!
Check: 
track.is_favorite? => true or false
The same works with the contacts of the logged-in user: 
another_user.add_contact!
another_user.remove_contact!
another_user.is_contact? => true or false
You can also check if another users follows some user or has a specific favorite: 

user.has_contact?(some_user) => true of false 
user.has_favorite?(some_track) => true or false