Skip to content

Commit 61f16d0

Browse files
adamintadamint
committed
document
1 parent 8c903e3 commit 61f16d0

File tree

5 files changed

+248
-26
lines changed

5 files changed

+248
-26
lines changed

‎.idea/misc.xml‎

Lines changed: 18 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ This library is available via Maven Central.
1515
<dependency>
1616
<groupId>com.adamratzman</groupId>
1717
<artifactId>spotify-web-api-kotlin</artifactId>
18-
<version>3.1.01</version>
18+
<version>3.1.1</version>
1919
</dependency>
2020
```
2121

2222
### Gradle
2323
```
24-
compile group: 'com.adamratzman', name: 'spotify-web-api-kotlin', version: '3.1.01'
24+
compile group: 'com.adamratzman', name: 'spotify-web-api-kotlin', version: '3.1.1'
2525
```
2626

2727
To use the latest snapshot instead, you must add the Jitpack repository

‎src/main/kotlin/com/adamratzman/spotify/endpoints/priv/library/UserLibraryAPI.kt‎

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,165 @@ package com.adamratzman.spotify.endpoints.priv.library
22

33
import com.adamratzman.spotify.main.SpotifyAPI
44
import com.adamratzman.spotify.utils.*
5+
import com.sun.org.apache.xpath.internal.operations.Bool
56
import java.util.function.Supplier
67

78
/**
89
* Endpoints for retrieving information about, and managing, tracks that the current user has saved in their “Your Music” library.
910
*/
1011
class UserLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
12+
/**
13+
* Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.
14+
*
15+
* @return Paging Object of [SavedTrack] ordered by position in library
16+
*/
1117
fun getSavedTracks(): SpotifyRestAction<PagingObject<SavedTrack>> {
1218
return toAction(Supplier {
1319
get("https://api.spotify.com/v1/me/tracks").toPagingObject<SavedTrack>(api = api)
1420
})
1521
}
1622

23+
/**
24+
* Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.
25+
*
26+
* @return Paging Object of [SavedAlbum] ordered by position in library
27+
*/
1728
fun getSavedAlbums(): SpotifyRestAction<PagingObject<SavedAlbum>> {
1829
return toAction(Supplier {
1930
get("https://api.spotify.com/v1/me/albums").toPagingObject<SavedAlbum>(api = api)
2031
})
2132
}
2233

23-
fun savedTracksContains(vararg ids: String): SpotifyRestAction<List<Boolean>> {
34+
/**
35+
* Check if a track is already saved in the current Spotify user’s ‘Your Music’ library.
36+
*
37+
* @throws BadRequestException if [id] is not found
38+
*/
39+
fun doesLibraryContainTrack(id: String): SpotifyRestAction<Boolean> {
40+
return toAction(Supplier {
41+
doesLibraryContainTracks(id).complete()[0]
42+
})
43+
}
44+
45+
/**
46+
* Check if a track is already saved in the current Spotify user’s ‘Your Music’ library.
47+
*
48+
* @throws BadRequestException if a provided id is not found
49+
*/
50+
fun doesLibraryContainTracks(vararg ids: String): SpotifyRestAction<List<Boolean>> {
2451
return toAction(Supplier {
2552
get("https://api.spotify.com/v1/me/tracks/contains?ids=${ids.joinToString(",") { it.encode() }}").toObject<List<Boolean>>(api)
2653
})
2754
}
2855

29-
fun savedAlbumsContains(vararg ids: String): SpotifyRestAction<List<Boolean>> {
56+
/**
57+
* Check if an album is already saved in the current Spotify user’s ‘Your Music’ library.
58+
*
59+
* @throws BadRequestException if id is not found
60+
*/
61+
fun doesLibraryContainAlbum(id: String): SpotifyRestAction<Boolean> {
62+
return toAction(Supplier {
63+
doesLibraryContainAlbums(id).complete()[0]
64+
})
65+
}
66+
67+
/**
68+
* Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library.
69+
*
70+
* @throws BadRequestException if any of the provided ids is invalid
71+
*/
72+
fun doesLibraryContainAlbums(vararg ids: String): SpotifyRestAction<List<Boolean>> {
3073
return toAction(Supplier {
3174
get("https://api.spotify.com/v1/me/albums/contains?ids=${ids.joinToString(",") { it.encode() }}").toObject<List<Boolean>>(api)
3275
})
3376
}
3477

35-
fun saveTracks(vararg ids: String): SpotifyRestAction<Unit> {
78+
/**
79+
* Save a track to the current user’s ‘Your Music’ library.
80+
*
81+
* @throws BadRequestException if the id is invalid
82+
*/
83+
fun addTrackToLibrary(id: String): SpotifyRestAction<Unit> {
84+
return toAction(Supplier {
85+
addTracksToLibrary(id).complete()
86+
})
87+
}
88+
89+
/**
90+
* Save one or more tracks to the current user’s ‘Your Music’ library.
91+
*
92+
* @throws BadRequestException if any of the provided ids is invalid
93+
*/
94+
fun addTracksToLibrary(vararg ids: String): SpotifyRestAction<Unit> {
3695
return toAction(Supplier {
3796
put("https://api.spotify.com/v1/me/tracks?ids=${ids.joinToString(",") { it.encode() }}")
3897
Unit
3998
})
4099
}
41100

42-
fun saveAlbums(vararg ids: String): SpotifyRestAction<Unit> {
101+
/**
102+
* Save an album to the current user’s ‘Your Music’ library.
103+
*
104+
* @throws BadRequestException if the id is invalid
105+
*/
106+
fun addAlbumToLibrary(id: String): SpotifyRestAction<Unit> {
107+
return toAction(Supplier {
108+
addAlbumsToLibrary(id).complete()
109+
})
110+
}
111+
112+
/**
113+
* Save one or more albums to the current user’s ‘Your Music’ library.
114+
*
115+
* @throws BadRequestException if any of the provided ids is invalid
116+
*/
117+
fun addAlbumsToLibrary(vararg ids: String): SpotifyRestAction<Unit> {
43118
return toAction(Supplier {
44119
put("https://api.spotify.com/v1/me/albums?ids=${ids.joinToString(",") { it.encode() }}")
45120
Unit
46121
})
47122
}
48123

49-
fun removeSavedTracks(vararg ids: String): SpotifyRestAction<Unit> {
124+
/**
125+
* Remove a track from the current user’s ‘Your Music’ library.
126+
*
127+
* @throws BadRequestException if the provided id is invalid
128+
*/
129+
fun removeTrackFromLibrary(id: String): SpotifyRestAction<Unit> {
130+
return toAction(Supplier {
131+
removeTracksFromLibrary(id).complete()
132+
})
133+
}
134+
135+
/**
136+
* Remove one or more tracks from the current user’s ‘Your Music’ library.
137+
*
138+
* @throws BadRequestException if any of the provided ids is invalid
139+
*/
140+
fun removeTracksFromLibrary(vararg ids: String): SpotifyRestAction<Unit> {
50141
return toAction(Supplier {
51142
delete("https://api.spotify.com/v1/me/tracks?ids=${ids.joinToString(",") { it.encode() }}")
52143
Unit
53144
})
54145
}
55146

56-
fun removeSavedAlbums(vararg ids: String): SpotifyRestAction<Unit> {
147+
/**
148+
* Remove an album from the current user’s ‘Your Music’ library.
149+
*
150+
* @throws BadRequestException if any of the provided ids is invalid
151+
*/
152+
fun removeAlbumFromLibrary(id: String): SpotifyRestAction<Unit> {
153+
return toAction(Supplier {
154+
removeAlbumsFromLibrary(id).complete()
155+
})
156+
}
157+
158+
/**
159+
* Remove one or more albums from the current user’s ‘Your Music’ library.
160+
*
161+
* @throws BadRequestException if any of the provided ids is invalid
162+
*/
163+
fun removeAlbumsFromLibrary(vararg ids: String): SpotifyRestAction<Unit> {
57164
return toAction(Supplier {
58165
delete("https://api.spotify.com/v1/me/albums?ids=${ids.joinToString(",") { it.encode() }}")
59166
Unit

‎src/main/kotlin/com/adamratzman/spotify/endpoints/priv/personalization/PersonalizationAPI.kt‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,36 @@ import java.util.function.Supplier
88
* Endpoints for retrieving information about the user’s listening habits.
99
*/
1010
class PersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
11-
11+
/**
12+
* Get the current user’s top artists based on calculated affinity.
13+
* Affinity is a measure of the expected preference a user has for a particular track or artist. It is based on user
14+
* behavior, including play history, but does not include actions made while in incognito mode. Light or infrequent
15+
* users of Spotify may not have sufficient play history to generate a full affinity data set. As a user’s behavior
16+
* is likely to shift over time, this preference data is available over three time spans. See time_range in the
17+
* query parameter table for more information. For each time range, the top 50 tracks and artists are available
18+
* for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
19+
* once each day for each user.
20+
*
21+
* @return [PagingObject] of full [Artist] objects sorted by affinity
22+
*/
1223
fun getTopArtists(): SpotifyRestAction<PagingObject<Artist>> {
1324
return toAction(Supplier {
1425
get("https://api.spotify.com/v1/me/top/artists").toPagingObject<Artist>(api = api)
1526
})
1627
}
1728

29+
/**
30+
* Get the current user’s top tracks based on calculated affinity.
31+
* Affinity is a measure of the expected preference a user has for a particular track or artist. It is based on user
32+
* behavior, including play history, but does not include actions made while in incognito mode. Light or infrequent
33+
* users of Spotify may not have sufficient play history to generate a full affinity data set. As a user’s behavior
34+
* is likely to shift over time, this preference data is available over three time spans. See time_range in the
35+
* query parameter table for more information. For each time range, the top 50 tracks and artists are available
36+
* for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
37+
* once each day for each user.
38+
*
39+
* @return [PagingObject] of full [Track] objects sorted by affinity
40+
*/
1841
fun getTopTracks(): SpotifyRestAction<PagingObject<Track>> {
1942
return toAction(Supplier {
2043
get("https://api.spotify.com/v1/me/top/tracks").toPagingObject<Track>(api = api)

‎src/main/kotlin/com/adamratzman/spotify/endpoints/priv/playlists/UserPlaylistAPI.kt‎

Lines changed: 91 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,45 @@ import java.util.function.Supplier
99
* Endpoints for retrieving information about a user’s playlists and for managing a user’s playlists.
1010
*/
1111
class UserPlaylistAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
12-
fun createPlaylist(userId: String, name: String, description: String, public: Boolean = true): SpotifyRestAction<Playlist> {
12+
/**
13+
* Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
14+
*
15+
* @param userId The user’s Spotify user ID.
16+
* @param name The name for the new playlist, for example "Your Coolest Playlist" . This name does not need to be
17+
* unique; a user may have several playlists with the same name.
18+
* @param description
19+
* @param public Defaults to true . If true the playlist will be public, if false it will be private.
20+
* To be able to create private playlists, the user must have granted the playlist-modify-private scope.
21+
* @param collaborative Defaults to false . If true the playlist will be collaborative. Note that to create a
22+
* collaborative playlist you must also set public to false . To create collaborative playlists you must have
23+
* granted playlist-modify-private and playlist-modify-public scopes.
24+
*
25+
* @return The created [Playlist] object with no tracks
26+
*/
27+
fun createPlaylist(userId: String, name: String, description: String? = null, public: Boolean? = null, collaborative: Boolean? = null): SpotifyRestAction<Playlist> {
1328
return toAction(Supplier {
14-
post("https://api.spotify.com/v1/users/${userId.encode()}/playlists",
15-
"{" +
16-
"\"name\": \"$name\"," +
17-
"\"description\": \"$description\"," +
18-
"\"public\": $public" +
19-
"}").toObject<Playlist>(api)
29+
val json = JSONObject()
30+
json.put("name", name)
31+
if (description != null) json.put("description", description)
32+
if (public != null) json.put("public", public)
33+
if (collaborative != null) json.put("collaborative", collaborative)
34+
post("https://api.spotify.com/v1/users/${userId.encode()}/playlists", json.toString()).toObject<Playlist>(api)
2035
})
2136
}
2237

2338
/**
24-
* [uris] <b>MUST BE</b> Spotify URIs, unlike nearly every other endpoint.
39+
* Add one or more tracks to a user’s playlist.
40+
*
41+
* @param userId The user’s Spotify user ID.
42+
* @param playlistId The Spotify ID for the playlist.
43+
* @param uris Spotify track ids. A maximum of 100 tracks can be added in one request.
44+
* @param position The position to insert the tracks, a zero-based index. For example, to insert the tracks in the
45+
* first position: position=0; to insert the tracks in the third position: position=2 . If omitted, the tracks will
46+
* be appended to the playlist. Tracks are added in the order they are listed in the query string or request body.
47+
*
48+
* @throws BadRequestException if any invalid track ids is provided or the playlist is not found
2549
*/
26-
fun addTrackToPlaylist(userId: String, playlistId: String, vararg uris: String, position: Int? = null): SpotifyRestAction<Unit> {
50+
fun addTracksToPlaylist(userId: String, playlistId: String, vararg uris: String, position: Int? = null): SpotifyRestAction<Unit> {
2751
val json = JSONObject().put("uris", uris.map { "spotify:track:${it.encode()}" })
2852
if (position != null) json.put("position", position)
2953
return toAction(Supplier {
@@ -32,6 +56,18 @@ class UserPlaylistAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
3256
})
3357
}
3458

59+
/**
60+
* Change a playlist’s name and public/private state. (The user must, of course, own the playlist.)
61+
*
62+
* @param userId The user’s Spotify user ID.
63+
* @param playlistId The Spotify ID for the playlist.
64+
* @param name Optional. The name to change the playlist to.
65+
* @param public Optional. Whether to make the playlist public or not.
66+
* @param collaborative Optional. Whether to make the playlist collaborative or not.
67+
* @param description Optional. Whether to change the description or not.
68+
*
69+
* @throws BadRequestException if the playlist is not found or parameters exceed the max length
70+
*/
3571
fun changePlaylistDescription(userId: String, playlistId: String, name: String? = null, public: Boolean? = null, collaborative: Boolean? = null,
3672
description: String? = null): SpotifyRestAction<Unit> {
3773
val json = JSONObject()
@@ -46,6 +82,14 @@ class UserPlaylistAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
4682
})
4783
}
4884

85+
/**
86+
* Get a list of the playlists owned or followed by a Spotify user.
87+
*
88+
* @param limit The maximum number of tracks to return. Default: 20. Minimum: 1. Maximum: 50.
89+
* @param offset The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of tracks.
90+
*
91+
* @throws BadRequestException if the filters provided are illegal
92+
*/
4993
fun getClientPlaylists(limit: Int = 20, offset: Int = 0): SpotifyRestAction<PagingObject<SimplePlaylist>> {
5094
if (limit !in 1..50) throw IllegalArgumentException("Limit must be between 1 and 50. Provided $limit")
5195
if (offset !in 0..100000) throw IllegalArgumentException("Offset must be between 0 and 100,000. Provided $limit")
@@ -54,20 +98,50 @@ class UserPlaylistAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
5498
})
5599
}
56100

57-
fun reorderTracks(userId: String, playlistId: String, reorderRangeStart: Int, reorderRangeLength: Int = 1, insertionPoint: Int, snapshotId: String? = null): SpotifyRestAction<Snapshot> {
101+
/**
102+
* Reorder a track or a group of tracks in a playlist.
103+
*
104+
* When reordering tracks, the timestamp indicating when they were added and the user who added them will be kept
105+
* untouched. In addition, the users following the playlists won’t be notified about changes in the playlists
106+
* when the tracks are reordered.
107+
*
108+
* @param userId The user’s Spotify user ID.
109+
* @param playlistId The Spotify ID for the playlist.
110+
* @param reorderRangeStart The position of the first track to be reordered.
111+
* @param reorderRangeLength
112+
* @param insertionPoint
113+
* @param snapshotId
114+
*
115+
* @throws BadRequestException if the playlist is not found or illegal filters are applied
116+
*/
117+
fun reorderTracks(userId: String, playlistId: String, reorderRangeStart: Int, reorderRangeLength: Int? = null, insertionPoint: Int, snapshotId: String? = null): SpotifyRestAction<Snapshot> {
58118
return toAction(Supplier {
59-
put("https://api.spotify.com/v1/users/${userId.encode()}/playlists/${playlistId.encode()}/tracks", "{" +
60-
"\"range_start\": $reorderRangeStart," +
61-
"\"range_length\": $reorderRangeLength," +
62-
"\"insert_before\": $insertionPoint" +
63-
if (snapshotId != null) ",\"snapshot_id\": \"$snapshotId\"" else "" +
64-
"}").toObject<Snapshot>(api)
119+
val json = JSONObject()
120+
json.put("range_start", reorderRangeStart)
121+
json.put("insert_before", insertionPoint)
122+
if (reorderRangeLength != null) json.put("range_length", reorderRangeLength)
123+
if (snapshotId != null) json.put("snapshot_id", snapshotId)
124+
put("https://api.spotify.com/v1/users/${userId.encode()}/playlists/${playlistId.encode()}/tracks", json.toString())
125+
.toObject<Snapshot>(api)
65126
})
66127
}
67128

129+
/**
130+
* Replace all the tracks in a playlist, overwriting its existing tracks. This powerful request can be useful
131+
* for replacing tracks, re-ordering existing tracks, or clearing the playlist.
132+
*
133+
* @param userId The user’s Spotify user ID.
134+
* @param playlistId The Spotify ID for the playlist.
135+
* @param trackIds The Spotify track ids.
136+
*
137+
* @throws BadRequestException if playlist is not found or illegal tracks are provided
138+
*/
68139
fun replaceTracks(userId: String, playlistId: String, vararg trackIds: String): SpotifyRestAction<Unit> {
69140
return toAction(Supplier {
70-
put("https://api.spotify.com/v1/users/${userId.encode()}/playlists/${playlistId.encode()}/tracks?uris=${trackIds.map { it.encode() }.joinToString(",") { "spotify:track:$it" }}")
141+
val json = JSONObject()
142+
json.put("uris", trackIds.map { "spotify:track:${it.encode()}" })
143+
put("https://api.spotify.com/v1/users/${userId.encode()}/playlists/${playlistId.encode()}/tracks",
144+
json.toString())
71145
Unit
72146
})
73147
}

0 commit comments

Comments
 (0)