soundcloud-ruby-api-wrapper 0.1.5 → 0.1.6

Sign up to get free protection for your applications and to get access to all the features.
Files changed (8) hide show
  1. data/README.html +164 -0
  2. data/VERSION.yml +1 -1
  3. data/lib/soundcloud/models/event.rb +0 -3
  4. data/lib/soundcloud/models/playlist.rb +1 -3
  5. data/lib/soundcloud/models/track.rb +7 -11
  6. data/lib/soundcloud/models/user.rb +16 -7
  7. data/spec/soundcloud_user_spec.rb +9 -0
  8. metadata +3 -1
data/README.html ADDED
@@ -0,0 +1,164 @@
1
+ <html>
2
+ <body>
3
+ <div id="description" style="width: 600px">
4
+
5
+ <h2>Getting started</h2>
6
+ <h3>Required Gems</h3>
7
+
8
+ <ul>
9
+ <li>activeresource gem</li>
10
+ <li>activesupport gem</li>
11
+ <li>multipart gem</li>
12
+ <li>oauth gem</li>
13
+ <li><a href="http://github.com/jwagener/oauth-active-resource">jwagener-oauth-active-resource</a> gem</li>
14
+ </ul>
15
+
16
+ <h3>Installation</h3>
17
+
18
+ First install all the missing required gems. To install the jwagener-oauth-active-resource gem you can use:
19
+
20
+ <pre>$ sudo gem install jwagener-oauth-active-resource -s http://gems.github.com</pre>
21
+
22
+ Then install the soundcloud api wrapper gem:
23
+
24
+ <pre>$ sudo gem install soundcloud-ruby-api-wrapper -s http://gems.github.com</pre>
25
+
26
+ <h3>Setup OAuth things</h3>
27
+
28
+ Look at <a href="http://wiki.github.com/soundcloud/api/oauth-example">http://wiki.github.com/soundcloud/api/oauth-example</a> to find out, how you setup your OAuth things.
29
+
30
+ <h3>First steps</h3>
31
+
32
+ Let's start with a simple app, which will find and display the hottest tracks. You don't need any OAuth authentication to do this.
33
+
34
+ <pre>
35
+ require 'rubygems'
36
+ gem 'soundcloud-ruby-api-wrapper'
37
+ require 'soundcloud'
38
+
39
+ # Create an anonymous soundcloud client
40
+ # if you prefer to work with sandbox-soundcloud.com, replace this with:
41
+ # sc_client = Soundcloud.register({:site => "http://api.sandbox-soundcloud.com"})
42
+ sc_client = Soundcloud.register
43
+
44
+ # Find the 10 hottest tracks
45
+ hot_tracks = sc_client.Track.find(:all,:params => {:order => 'order', :limit => 10})
46
+
47
+ # and display their titles
48
+ p '==the 10 hottest tracks=='
49
+ hot_tracks.each do |track|
50
+ p track.title
51
+ end
52
+ </pre>
53
+
54
+ To test authentication you can use this small app, which will dispay the name of the logged in user.
55
+
56
+ <pre>
57
+ require 'rubygems'
58
+ gem 'soundcloud-ruby-api-wrapper'
59
+ require 'soundcloud'
60
+
61
+ gem 'oauth'
62
+ require 'oauth'
63
+
64
+
65
+ # Create a Soundcloud OAuth consumer token object
66
+ sc_consumer = Soundcloud.consumer('YOUR_APPLICATION_CONSUMER_TOKEN','YOUR_APPLICATION_CONSUMER_SECRET')
67
+
68
+ # Create an OAuth access token object
69
+ access_token = OAuth::AccessToken.new(sc_consumer, 'YOUR_OAUTH_ACCESS_TOKEN', 'YOUR_OAUTH_ACCESS_SECRET')
70
+
71
+ # Create an authenticated Soundcloud client, based on the access token
72
+ sc_client = Soundcloud.register({ :access_token => access_token})
73
+
74
+ # Get the logged in user
75
+ my_user = sc_client.User.find_me
76
+
77
+ # Display his full name
78
+ p "Hello, my name is #{my_user.full_name}"
79
+
80
+ </pre>
81
+
82
+ Find more examples in the "Model ..." pages.
83
+
84
+
85
+ <h2>Sub-resources</h2>
86
+
87
+ The Soundcloud API provides 3 different types of sub-resources:
88
+ <h3>Nested</h3>
89
+
90
+ These are directly embedded in the response. For example a playlist has a track array.
91
+
92
+ <pre>playlist.tracks</pre>
93
+
94
+ When saving the original resource, the nested array will be saved as well.
95
+
96
+ <pre>playlist.tracks.push some_track
97
+ playlist.save
98
+ </pre>
99
+
100
+ <h3>Separate</h3>
101
+
102
+ These are separated from the original resource.
103
+ Example:
104
+ A Track has the path "/tracks/[TRACK ID]"
105
+ This track has a collection of users, which have access to this track, called permissions.
106
+ These can be accessed via the path "/tracks/[TRACK ID]/permission".
107
+
108
+ In ruby they are accessed like nested resources:
109
+
110
+ <pre>playlist.permissions</pre>
111
+
112
+ But have to be saved explicitly:
113
+ <pre>
114
+ playlist.permissions.push some_user
115
+ playlist.permissions.save
116
+ playlist.save</pre>
117
+
118
+ A lot of these collections are partials, that means Soundcloud API will not return more than 50 items per request.
119
+ For example the user famous_dj has 120 fans/followers. famous_dj.fans will only return 50 fans.
120
+ To get all fans you have to do something like this:
121
+ <pre>
122
+ fans = []
123
+ limit = 50
124
+ begin
125
+ some_fans = famous_dj.fans({:offset => fans.count, :limit => limit})
126
+ fans += some_fans
127
+ end while some_fans.count >= limit
128
+ </pre>
129
+
130
+ The array fans now contains all fans/followers of famous_dj.
131
+
132
+
133
+ <h3>'Single changeable' separate</h3>
134
+
135
+ Some separate collections can't be saved in a bulk request. Instead each item has to be added or removed explicitly.
136
+ For now this only affects the contacts (followees) and favorites of a user.
137
+
138
+ To add a track to the logged-in users favorites:
139
+
140
+ <pre>track.add_favorite!</pre>
141
+
142
+ Remove:
143
+
144
+ <pre>track.remove_favorite!</pre>
145
+
146
+ Check:
147
+
148
+ <pre>track.is_favorite? => true or false</pre>
149
+
150
+ The same works with the contacts of the logged-in user:
151
+
152
+ <pre>another_user.add_contact!
153
+ another_user.remove_contact!
154
+ another_user.is_contact? => true or false
155
+ </pre>
156
+
157
+ You can also check if another users follows some user or has a specific favorite:
158
+
159
+ <pre>
160
+ user.has_contact?(some_user) => true of false
161
+ user.has_favorite?(some_track) => true or false</pre>
162
+
163
+
164
+ </div></body></html>
data/VERSION.yml CHANGED
@@ -1,4 +1,4 @@
1
1
  ---
2
2
  :major: 0
3
3
  :minor: 1
4
- :patch: 5
4
+ :patch: 6
data/lib/soundcloud/models/event.rb CHANGED
@@ -1,8 +1,5 @@
1
1
  module Soundcloud
2
2
  module Models
3
-
4
- # Soundcloud Event resource
5
- #
6
3
  # Look up the resource attributes and filtering usage here:
7
4
  #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#event
data/lib/soundcloud/models/playlist.rb CHANGED
@@ -1,8 +1,6 @@
1
1
  module Soundcloud
2
2
  module Models
3
- # Soundcloud Playlist resource
4
- #
5
- # Note: At the moment, you cant create or delete playlists via Soundcloud API
3
+ # Note: At the moment, you can't create or delete playlists via Soundcloud API
6
4
  #
7
5
  # Look up the resource attributes and filtering usage here:
8
6
  #
data/lib/soundcloud/models/track.rb CHANGED
@@ -1,21 +1,18 @@
1
1
  module Soundcloud
2
- module Models
3
-
4
- # Soundcloud Track resource
5
- #
2
+ module Models
6
3
  # Look up the resource attributes and filtering usage here:
7
- #
4
+ #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#track
9
6
  #
10
7
  # Examples:
11
8
  #
12
- # # gets the tracks from some_user
13
- # some_user_tracks = sc_client.Track.find(:all, :from => '/users/some_user/tracks')
9
+ # # gets 50 (Soundcloud API limit) tracks from some_user
10
+ # some_user_tracks = some_user.tracks
14
11
  #
15
12
  # # gets the first song from some_user_tracks
16
13
  # first_song = some_user_tracks.first
17
14
  #
18
- # # prints all comments of first_song with username, timestamp (can be nil) and comment body
15
+ # # prints 50 (Soundcloud API limit) comments of first_song with username, timestamp (can be nil) and comment body
19
16
  # first_song.comments.each do |comment|
20
17
  # if comment.timestamp.nil?
21
18
  # timestamp = ""
@@ -26,9 +23,10 @@ module Soundcloud
26
23
  # end
27
24
  #
28
25
  #
29
- # # gets tracks with a BPM <= 100
26
+ # # gets 50 (Soundcloud API limit) tracks with a BPM <= 100
30
27
  # slow_tracks = sc_client.Track.find(:all, :params => { "bpm[to]" => "100"} )
31
28
  #
29
+ #
32
30
  # # create a new Track on Soundcloud with some_sound_file.mp3 as asset data
33
31
  # new_track = sc_client.Track.new
34
32
  # new_track.title = 'New Track'
@@ -55,8 +53,6 @@ module Soundcloud
55
53
 
56
54
  cattr_accessor :element_name
57
55
  self.element_name = 'track'
58
-
59
-
60
56
 
61
57
  def download
62
58
  raise Exception.new('Track is not downloadable') if not downloadable
data/lib/soundcloud/models/user.rb CHANGED
@@ -1,10 +1,7 @@
1
1
  module Soundcloud
2
2
  module Models
3
-
4
- # Soundcloud User resource
5
- #
6
3
  # Look up the resource attributes and filtering usage here:
7
- #
4
+ #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#user
9
6
  #
10
7
  # Examples:
@@ -29,15 +26,24 @@ module Soundcloud
29
26
  # joe2.add_contact!
30
27
  #
31
28
  #
32
- # # Display all tracks of a user
29
+ # # Display 50 (Soundcloud API limit) tracks of a user
33
30
  # user = sc_client.User.find('some-user')
34
31
  # user.tracks.each do |track|
35
32
  # p track.title
36
33
  # end
37
-
34
+ #
35
+ # # Get all fans of a user
36
+ # fans = []
37
+ # limit = 50
38
+ # begin
39
+ # some_fans = famous_dj.fans({:offset => fans.count, :limit => limit})
40
+ # fans += some_fans
41
+ # end while some_fans.count >= limit
42
+ #
43
+ #
38
44
 
39
45
  class User < Base
40
- has_many :tracks, :contacts, :comments, :favorites, :playlists
46
+ has_many :tracks, :contacts, :comments, :favorites, :playlists, :fans
41
47
  has_many_single_changeable :contacts, :favorites
42
48
  can_be_a_single_changeable :contact
43
49
 
@@ -55,6 +61,9 @@ module Soundcloud
55
61
 
56
62
  class Contact < User #:nodoc:
57
63
  end
64
+
65
+ class Fan < User #:nodoc:
66
+ end
58
67
  end
59
68
  end
60
69
 
data/spec/soundcloud_user_spec.rb CHANGED
@@ -53,6 +53,15 @@ describe "Soundcloud::Models::User" do
53
53
  my_user = @sc.User.find_me
54
54
  my_user.username.should_not be nil
55
55
  end
56
+
57
+ it 'should find some fans of a user' do
58
+ @api_test_2.fans.count.should be >= 1
59
+ end
60
+
61
+ it 'should find exactly one fan / two fans' do
62
+ @api_test_2.fans({:limit => 1}).count.should be == 1
63
+ @api_test_2.fans({:limit => 2}).count.should be == 2
64
+ end
56
65
 
57
66
  end
58
67
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: soundcloud-ruby-api-wrapper
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.5
4
+ version: 0.1.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - Johannes Wagener
@@ -40,9 +40,11 @@ extensions: []
40
40
 
41
41
  extra_rdoc_files:
42
42
  - LICENSE
43
+ - README.html
43
44
  - README.rdoc
44
45
  files:
45
46
  - LICENSE
47
+ - README.html
46
48
  - README.rdoc
47
49
  - Rakefile
48
50
  - VERSION.yml