Class: SpotifyWebApi::AlbumsController

Inherits:
BaseController show all
Defined in:
lib/spotify_web_api/controllers/albums_controller.rb

Overview

AlbumsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_api_call_builder, #new_parameter, #new_request_builder, #new_response_handler, user_agent

Constructor Details

This class inherits a constructor from SpotifyWebApi::BaseController

Instance Method Details

#check_users_saved_albums(ids) ⇒ Array[TrueClass | FalseClass]

Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library.

Parameters:

  • ids (String) —

    Required parameter: Example:

Returns:

  • (Array[TrueClass | FalseClass]) —

    response from the API call



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 231

def check_users_saved_albums(ids)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/me/albums/contains',
                                 Server::DEFAULT)
               .query_param(new_parameter(ids, key: 'ids'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:deserialize_primitive_types))
                .is_api_response(true)
                .is_response_array(true)
                .is_primitive_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#get_an_album(id, market: nil) ⇒ AlbumObject

Get Spotify catalog information for a single album.

Parameters:

  • id (String) —

    Required parameter: Example:

  • market (String) (defaults to: nil) —

    Optional parameter: Example:

Returns:



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 13

def get_an_album(id,
                 market: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/albums/{id}',
                                 Server::DEFAULT)
               .template_param(new_parameter(id, key: 'id')
                                .should_encode(true))
               .query_param(new_parameter(market, key: 'market'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AlbumObject.method(:from_hash))
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#get_an_albums_tracks(id, market: nil, limit: 20, offset: 0) ⇒ PagingSimplifiedTrackObject

Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of tracks returned.

Parameters:

  • id (String) —

    Required parameter: Example:

  • market (String) (defaults to: nil) —

    Optional parameter: Example:

  • limit (Integer) (defaults to: 20) —

    Optional parameter: Example:20

  • offset (Integer) (defaults to: 0) —

    Optional parameter: Example:0

Returns:



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 86

def get_an_albums_tracks(id,
                         market: nil,
                         limit: 20,
                         offset: 0)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/albums/{id}/tracks',
                                 Server::DEFAULT)
               .template_param(new_parameter(id, key: 'id')
                                .should_encode(true))
               .query_param(new_parameter(market, key: 'market'))
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(offset, key: 'offset'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PagingSimplifiedTrackObject.method(:from_hash))
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#get_multiple_albums(ids, market: nil) ⇒ ManyAlbums

Get Spotify catalog information for multiple albums identified by their Spotify IDs.

Parameters:

  • ids (String) —

    Required parameter: Example:

  • market (String) (defaults to: nil) —

    Optional parameter: Example:

Returns:



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 49

def get_multiple_albums(ids,
                        market: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/albums',
                                 Server::DEFAULT)
               .query_param(new_parameter(ids, key: 'ids'))
               .query_param(new_parameter(market, key: 'market'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ManyAlbums.method(:from_hash))
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#get_new_releases(limit: 20, offset: 0) ⇒ PagedAlbums

Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

Parameters:

  • limit (Integer) (defaults to: 20) —

    Optional parameter: Example:20

  • offset (Integer) (defaults to: 0) —

    Optional parameter: Example:0

Returns:



265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 265

def get_new_releases(limit: 20,
                     offset: 0)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/browse/new-releases',
                                 Server::DEFAULT)
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(offset, key: 'offset'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PagedAlbums.method(:from_hash))
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#get_users_saved_albums(limit: 20, offset: 0, market: nil) ⇒ PagingSavedAlbumObject

Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.

Parameters:

  • limit (Integer) (defaults to: 20) —

    Optional parameter: Example:20

  • offset (Integer) (defaults to: 0) —

    Optional parameter: Example:0

  • market (String) (defaults to: nil) —

    Optional parameter: Example:

Returns:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 127

def get_users_saved_albums(limit: 20,
                           offset: 0,
                           market: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/me/albums',
                                 Server::DEFAULT)
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(offset, key: 'offset'))
               .query_param(new_parameter(market, key: 'market'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PagingSavedAlbumObject.method(:from_hash))
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#remove_albums_user(ids, body: nil) ⇒ void

This method returns an undefined value.

Remove one or more albums from the current user’s ‘Your Music’ library.

Parameters:

  • ids (String) —

    Required parameter: Example:

  • body (MeAlbumsRequest) (defaults to: nil) —

    Optional parameter: Example:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 197

def remove_albums_user(ids,
                       body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/me/albums',
                                 Server::DEFAULT)
               .query_param(new_parameter(ids, key: 'ids'))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .is_response_void(true)
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end

#save_albums_user(ids, body: nil) ⇒ void

This method returns an undefined value.

Save one or more albums to the current user’s ‘Your Music’ library.

Parameters:

  • ids (String) —

    Required parameter: Example:

  • body (MeAlbumsRequest) (defaults to: nil) —

    Optional parameter: Example:



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/spotify_web_api/controllers/albums_controller.rb', line 163

def save_albums_user(ids,
                     body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/me/albums',
                                 Server::DEFAULT)
               .query_param(new_parameter(ids, key: 'ids'))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('oauth_2_0')))
    .response(new_response_handler
                .is_response_void(true)
                .is_api_response(true)
                .local_error('401',
                             "Bad or expired token. This can happen if the user revoked a'\
                              ' token or\nthe access token has expired. You should'\
                              ' re-authenticate the user.\n",
                             UnauthorizedException)
                .local_error('403',
                             "Bad OAuth request (wrong consumer key, bad nonce, expired'\
                              '\ntimestamp...). Unfortunately, re-authenticating the user'\
                              ' won't help here.\n",
                             ForbiddenException)
                .local_error('429',
                             "The app has exceeded its rate limits.\n",
                             TooManyRequestsException))
    .execute
end