Class: Soundcloud::API

Inherits:
Object
  • Object
show all
Defined in:
lib/soundcloud/api.rb

Constant Summary collapse

DEFAULT_ACCEPT = 
"application/json".freeze
DEFAULT_HOST = 
'https://api.soundcloud.com'
AUTHORIZE_URL = 
'https://soundcloud.com/connect'
TOKEN_PATH = 
'/oauth2/token'
SUBRESOURCE_MAP =

RESTful API definitions:

{
  user: [:tracks, :playlists, :groups, :web_profiles, :followings, :followers, :comments, :favorites, :connections, :activities],
  track: [:comments, :favoriters, [:shared_to_users, "shared-to/users"], [:shared_to_emails, "shared-to/emails"], :secret_token],
  playlist: [[:shared_to_users, "shared-to/users"], [:shared_to_emails, "shared-to/emails"], :secret_token],
  group: [:moderators, :members, :contributors, :users, :tracks, :pending_tracks, :contributions],
  app: [:tracks]
}

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(token, opts = {}) ⇒ API

Options :verbose whether to print request/response. Request bodies are printed too :mime Content of the Accept header, indicates the format of the response. Default is json :stubs Instance of Faraday::Adapter::Test::Stubs, which will be used instead of the default adapter.



86
87
88
89
90
 
# File 'lib/soundcloud/api.rb', line 86

def initialize(token, opts={})
  self.token = token
  self.verbose = !!opts[:verbose]
  self.stubs = opts[:stubs]
end

Class Attribute Details

.adapter ⇒ Object (readonly)

Returns the value of attribute adapter.



19
20
21
 
# File 'lib/soundcloud/api.rb', line 19

def adapter
  @adapter
end

.client_id ⇒ Object (readonly)

Returns the value of attribute client_id.



18
19
20
 
# File 'lib/soundcloud/api.rb', line 18

def client_id
  @client_id
end

.client_secret ⇒ Object (readonly)

Returns the value of attribute client_secret.



18
19
20
 
# File 'lib/soundcloud/api.rb', line 18

def client_secret
  @client_secret
end

.host ⇒ Object (readonly)

Returns the value of attribute host.



19
20
21
 
# File 'lib/soundcloud/api.rb', line 19

def host
  @host
end

.mime ⇒ Object (readonly)

Returns the value of attribute mime.



19
20
21
 
# File 'lib/soundcloud/api.rb', line 19

def mime
  @mime
end

.redirect_uri ⇒ Object (readonly)

Returns the value of attribute redirect_uri.



18
19
20
 
# File 'lib/soundcloud/api.rb', line 18

def redirect_uri
  @redirect_uri
end

Instance Attribute Details

#host ⇒ Object

Returns the value of attribute host.



80
81
82
 
# File 'lib/soundcloud/api.rb', line 80

def host
  @host
end

#stubs ⇒ Object

Returns the value of attribute stubs.



79
80
81
 
# File 'lib/soundcloud/api.rb', line 79

def stubs
  @stubs
end

#token ⇒ Object

Returns the value of attribute token.



80
81
82
 
# File 'lib/soundcloud/api.rb', line 80

def token
  @token
end

#verbose ⇒ Object

Returns the value of attribute verbose.



79
80
81
 
# File 'lib/soundcloud/api.rb', line 79

def verbose
  @verbose
end

Class Method Details

.authorize_url ⇒ Object

Raises:



48
49
50
51
 
# File 'lib/soundcloud/api.rb', line 48

def authorize_url
  raise Soundcloud::Error::Unauthorized, "Missing configuration" unless client_id and client_secret and redirect_uri
  "https://#{AUTHORIZE_URL}?response_type=code&client_id=#{client_id}&redirect_uri=#{URI.escape redirect_uri}&scope=non-expiring"
end

.configure(options = {}) ⇒ Object 



21
22
23
24
25
26
27
28
 
# File 'lib/soundcloud/api.rb', line 21

def configure(options={})
  @client_id = options[:client_id]
  @client_secret = options[:client_secret]
  @redirect_uri = options[:redirect_uri]
  @mime = options[:mime] if options.key? :mime
  @host = options[:host] if options.key? :host
  @adapter = options[:adapter] if options[:adapter]
end

.connection(opts = {}) ⇒ Object

Establish a class-wide connection, possibly to be able to use persistent connections among requests and event-based things.



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/soundcloud/api.rb', line 36

def connection(opts={})
  @@connections ||= {}
  @@connections[opts] ||= Faraday.new(self.host, headers: {accept: self.mime, user_agent: self.user_agent}) do |builder|
    builder.request :multipart
    builder.request :url_encoded
    builder.use Soundcloud::Middleware::RaiseError
    builder.response :json, content_type: /\bjson$/
    builder.response :logger if opts[:verbose]
    builder.adapter self.adapter
  end
end

.exchange_temporary_credentials(code, stubs = nil) ⇒ Object

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/soundcloud/api.rb', line 53

def exchange_temporary_credentials(code, stubs=nil)
  raise Soundcloud::Error::Unauthorized, "Missing configuration" unless client_id and client_secret and redirect_uri
  begin
    parameters = {
      client_id: client_id, client_secret: client_secret, redirect_uri: redirect_uri,
      grant_type: 'authorization_code', code: code
    }
    Faraday.new do |builder|
      builder.request :url_encoded
      builder.response :json, content_type: /\bjson$/
      builder.adapter *Array(stubs ? [:test, stubs] : self.adapter)
    end.post("#{host}#{TOKEN_PATH}") do |request|
      request.body parameters
    end
  rescue
    raise Soundcloud::Error::Unauthorized, "<#{$!.class}: #{$!}>"
  end
end

.user_agent ⇒ Object 



30
31
32
 
# File 'lib/soundcloud/api.rb', line 30

def user_agent
  "Soundcloud client v#{Soundcloud::VERSION}"
end

Instance Method Details

#auth_header ⇒ Object 



184
185
186
 
# File 'lib/soundcloud/api.rb', line 184

def auth_header
  { authorization: "OAuth #{self.token}" } if self.token and !self.token.empty?
end

#connection(options = {}) ⇒ Object 



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/soundcloud/api.rb', line 93

def connection(options={})
  options[:verbose] = self.verbose unless options.key?(:verbose) or !self.verbose
  stubs = options.delete(:stubs) || self.stubs
  conn = self.class.connection(options)
  if stubs
    conn = conn.dup
    conn.builder.handlers.delete_at -1
    conn.builder.adapter :test, self.stubs
  end
  conn
end

#favorite!(track) ⇒ Object Also known as: favorite 



147
148
149
 
# File 'lib/soundcloud/api.rb', line 147

def favorite!(track)
  put "/users/me/favorites/#{id_of track}"
end

#favorite?(track, who = "me") ⇒ Boolean

Returns:

  • (Boolean) 


157
158
159
160
161
 
# File 'lib/soundcloud/api.rb', line 157

def favorite?(track, who="me")
  get "/users/#{id_of who}/favorites/#{id_of track}"
rescue Soundcloud::Error::NotFound
  false
end

#follow!(user) ⇒ Object 



163
164
165
 
# File 'lib/soundcloud/api.rb', line 163

def follow!(user)
  put "/users/me/followings/#{id_of user}"
end

#follow?(user, who = "me") ⇒ Boolean

Returns:

  • (Boolean) 


173
174
175
176
177
 
# File 'lib/soundcloud/api.rb', line 173

def follow?(user, who="me")
  get "/users/#{id_of who}/followings/#{id_of user}"
rescue Soundcloud::Error::NotFound
  false
end

#id_of(item) ⇒ Object 



179
180
181
182
 
# File 'lib/soundcloud/api.rb', line 179

def id_of(item)
  id = item["id"] || item[:id] if item.is_a?(Hash)
  id || item
end

#unfavorite!(track) ⇒ Object Also known as: unfavorite 



152
153
154
 
# File 'lib/soundcloud/api.rb', line 152

def unfavorite!(track)
  delete "/users/me/favorites/#{id_of track}"
end

#unfollow!(user) ⇒ Object 



167
168
169
170
171
 
# File 'lib/soundcloud/api.rb', line 167

def unfollow!(user)
  delete "/users/me/followings/#{id_of user}"
rescue Soundcloud::Error::NotFound
  false
end