Merge pull request #185 from adamint/dev

Dev

Author: adamint

README.md

@@ -1,5 +1,5 @@
 # Kotlin Spotify Web API 
-[ ![JCenter Download](https://api.bintray.com/packages/bintray/jcenter/com.adamratzman%3Aspotify-api-kotlin/images/download.svg) ](https://bintray.com/bintray/jcenter/com.adamratzman%3Aspotify-api-kotlin/_latestVersion)
+[![JCenter](https://maven-badges.herokuapp.com/maven-central/com.adamratzman/spotify-api-kotlin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.adamratzman/spotify-api-kotlin)
 [![Build Status](http://144.217.240.243:8111/app/rest/builds/aggregated/strob:(buildType:(project:(id:SpotifyWebApiKotlin)))/statusIcon.svg)](http://144.217.240.243:8111/project.html?projectId=SpotifyWebApiKotlin) 
 [![](https://img.shields.io/badge/Documentation-latest-orange.svg)](https://adamint.github.io/spotify-web-api-kotlin/docs/spotify-web-api-kotlin/)
 ![](https://img.shields.io/badge/License-MIT-blue.svg)

build.gradle.kts

@@ -15,7 +15,7 @@ plugins {
 }
 
 group = "com.adamratzman"
-version = "3.0.0"
+version = "3.0.01"
 
 java {
     withSourcesJar()

src/commonMain/kotlin/com.adamratzman.spotify/Builder.kt

@@ -55,7 +55,8 @@ internal const val base = "https://api.spotify.com/v1"
  * @property browse Provides access to Spotify [browse endpoints](https://developer.spotify.com/documentation/web-api/reference/browse/)
  * @property artists Provides access to Spotify [artist endpoints](https://developer.spotify.com/documentation/web-api/reference/artists/)
  * @property tracks Provides access to Spotify [track endpoints](https://developer.spotify.com/documentation/web-api/reference/tracks/)
- *
+ * @property defaultLimit The default amount of objects to retrieve in one request
+ * @property json The Json serializer/deserializer instance
  * @property logger The Spotify event logger
  *
  */
@@ -69,6 +70,8 @@ sealed class SpotifyApi<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>(
     var retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean,
+    var defaultLimit: Int,
+    var allowBulkRequests: Boolean,
     var json: Json
 ) {
     var useCache = useCache
@@ -349,6 +352,8 @@ class SpotifyAppApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean,
+    defaultLimit: Int,
+    allowBulkRequests: Boolean,
     json: Json
 ) : SpotifyApi<SpotifyAppApi, SpotifyAppApiBuilder>(
         clientId,
@@ -360,6 +365,8 @@ class SpotifyAppApi internal constructor(
         retryWhenRateLimited,
         enableLogger,
         testTokenValidity,
+        defaultLimit,
+        allowBulkRequests,
         json
 ) {
     constructor(
@@ -377,6 +384,8 @@ class SpotifyAppApi internal constructor(
             options.retryWhenRateLimited,
             options.enableLogger,
             options.testTokenValidity,
+            options.defaultLimit,
+            options.allowBulkRequests,
             options.json
     )
 
@@ -453,6 +462,8 @@ class SpotifyClientApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean,
+    defaultLimit: Int,
+    allowBulkRequests: Boolean,
     json: Json
 ) : SpotifyApi<SpotifyClientApi, SpotifyClientApiBuilder>(
         clientId,
@@ -464,6 +475,8 @@ class SpotifyClientApi internal constructor(
         retryWhenRateLimited,
         enableLogger,
         testTokenValidity,
+        defaultLimit,
+        allowBulkRequests,
         json
 ) {
     constructor(
@@ -483,6 +496,8 @@ class SpotifyClientApi internal constructor(
             options.retryWhenRateLimited,
             options.enableLogger,
             options.testTokenValidity,
+            options.defaultLimit,
+            options.allowBulkRequests,
             options.json
     )
 

src/commonMain/kotlin/com.adamratzman.spotify/SpotifyApi.kt

@@ -65,8 +65,8 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
     fun isFollowingPlaylist(playlistId: String): SpotifyRestAction<Boolean> {
         return toAction {
             isFollowingPlaylist(
-                playlistId,
-                (api as SpotifyClientApi).userId
+                    playlistId,
+                    (api as SpotifyClientApi).userId
             ).complete()
         }
     }
@@ -86,8 +86,8 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
     fun isFollowingUsers(vararg users: String): SpotifyRestAction<List<Boolean>> {
         return toAction {
             get(
-                EndpointBuilder("/me/following/contains").with("type", "user")
-                    .with("ids", users.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
+                    EndpointBuilder("/me/following/contains").with("type", "user")
+                            .with("ids", users.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
             ).toList(Boolean.serializer().list, api, json)
         }
     }
@@ -125,8 +125,8 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
     fun isFollowingArtists(vararg artists: String): SpotifyRestAction<List<Boolean>> {
         return toAction {
             get(
-                EndpointBuilder("/me/following/contains").with("type", "artist")
-                    .with("ids", artists.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
+                    EndpointBuilder("/me/following/contains").with("type", "artist")
+                            .with("ids", artists.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
             ).toList(Boolean.serializer().list, api, json)
         }
     }
@@ -138,22 +138,22 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/follow/get-followed/)**
      *
-     * @param limit The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param limit The maximum number of items to return. Default: 50 (or api limit). Minimum: 1. Maximum: 50.
      * @param after The last artist ID retrieved from the previous request.
      *
      * @return [CursorBasedPagingObject] ([Information about them](https://github.com/adamint/spotify-web-api-kotlin/blob/master/README.md#the-benefits-of-linkedresults-pagingobjects-and-cursor-based-paging-objects)
      * with full [Artist] objects
      */
     fun getFollowedArtists(
-        limit: Int? = null,
+        limit: Int? = api.defaultLimit,
         after: String? = null
     ): SpotifyRestActionPaging<Artist, CursorBasedPagingObject<Artist>> {
         return toActionPaging {
             get(
-                EndpointBuilder("/me/following").with("type", "artist").with("limit", limit).with(
-                    "after",
-                    after
-                ).toString()
+                    EndpointBuilder("/me/following").with("type", "artist").with("limit", limit).with(
+                            "after",
+                            after
+                    ).toString()
             ).toCursorBasedPagingObject(Artist.serializer(), "artists", this, json)
         }
     }
@@ -180,14 +180,19 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/follow/follow-artists-users/)**
      *
+     * @param users User ids or uris. Maximum **50**.
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followUsers(vararg users: String): SpotifyRestAction<Unit> {
+        if (users.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many users (${users.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many users were provided"))
         return toAction {
-            put(
-                EndpointBuilder("/me/following").with("type", "user")
-                    .with("ids", users.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
-            )
+            users.toList().chunked(50).forEach { list ->
+                put(
+                        EndpointBuilder("/me/following").with("type", "user")
+                                .with("ids", list.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
+                )
+            }
             Unit
         }
     }
@@ -214,14 +219,19 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/follow/follow-artists-users/)**
      *
+     * @param artists User ids or uris. Maximum **50**.
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followArtists(vararg artists: String): SpotifyRestAction<Unit> {
+        if (artists.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many artists (${artists.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many artists were provided"))
         return toAction {
-            put(
-                EndpointBuilder("/me/following").with("type", "artist")
-                    .with("ids", artists.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
-            )
+            artists.toList().chunked(50).forEach { list ->
+                put(
+                        EndpointBuilder("/me/following").with("type", "artist")
+                                .with("ids", list.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
+                )
+            }
             Unit
         }
     }
@@ -248,8 +258,8 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
     fun followPlaylist(playlist: String, followPublicly: Boolean = true): SpotifyRestAction<Unit> {
         return toAction {
             put(
-                EndpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString(),
-                "{\"public\": $followPublicly}"
+                    EndpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString(),
+                    "{\"public\": $followPublicly}"
             )
             Unit
         }
@@ -279,16 +289,19 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-artists-users/)**
      *
-     * @param users The users to be unfollowed from
+     * @param users The users to be unfollowed from. Maximum **50**.
      *
      * @throws BadRequestException if an invalid id is provided
      */
     fun unfollowUsers(vararg users: String): SpotifyRestAction<Unit> {
+        if (users.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many users (${users.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many users were provided"))
         return toAction {
-            delete(
-                EndpointBuilder("/me/following").with("type", "user")
-                    .with("ids", users.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
-            )
+            users.toList().chunked(50).forEach { list ->
+                delete(
+                        EndpointBuilder("/me/following").with("type", "user")
+                                .with("ids", list.joinToString(",") { UserUri(it).id.encodeUrl() }).toString()
+                )
+            }
             Unit
         }
     }
@@ -317,16 +330,20 @@ class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/follow/unfollow-artists-users/)**
      *
-     * @param artists The artists to be unfollowed from
+     * @param artists The artists to be unfollowed from. Maximum **50**.
+     *
      *
      * @throws BadRequestException if an invalid id is provided
      */
     fun unfollowArtists(vararg artists: String): SpotifyRestAction<Unit> {
+        if (artists.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many artists (${artists.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many artists were provided"))
         return toAction {
-            delete(
-                EndpointBuilder("/me/following").with("type", "artist")
-                    .with("ids", artists.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
-            )
+            artists.toList().chunked(50).forEach { list ->
+                delete(
+                        EndpointBuilder("/me/following").with("type", "artist")
+                                .with("ids", list.joinToString(",") { ArtistUri(it).id.encodeUrl() }).toString()
+                )
+            }
             Unit
         }
     }

src/commonMain/kotlin/com.adamratzman.spotify/endpoints/client/ClientFollowingApi.kt

@@ -36,15 +36,15 @@ class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-tracks/)**
      *
-     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param limit The number of objects to return. Default: 50 (or api limit). Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
      * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
      * If omitted, the returned items will be relevant to all countries.
      *
      * @return [PagingObject] of [SavedTrack] ordered by position in library
      */
     fun getSavedTracks(
-        limit: Int? = null,
+        limit: Int? = api.defaultLimit,
         offset: Int? = null,
         market: Market? = null
     ): SpotifyRestActionPaging<SavedTrack, PagingObject<SavedTrack>> {
@@ -63,15 +63,15 @@ class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-albums/)**
      *
-     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param limit The number of objects to return. Default: 50 (or api limit). Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
      * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
      * If omitted, the returned items will be relevant to all countries.
      *
      * @return Paging Object of [SavedAlbum] ordered by position in library
      */
     fun getSavedAlbums(
-        limit: Int? = null,
+        limit: Int? = api.defaultLimit,
         offset: Int? = null,
         market: Market? = null
     ): SpotifyRestActionPaging<SavedAlbum, PagingObject<SavedAlbum>> {
@@ -109,16 +109,19 @@ class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/library/)**
      *
      * @param type The type of objects (album or track)
-     * @param ids The spotify ids or uris of the objects
+     * @param ids The spotify ids or uris of the objects. Maximum **50** ids.
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun contains(type: LibraryType, vararg ids: String): SpotifyRestAction<List<Boolean>> {
+        if (ids.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many ids (${ids.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many ids were provided"))
         return toAction {
-            get(
-                EndpointBuilder("/me/$type/contains").with("ids", ids.joinToString(",") { type.id(it).encodeUrl() })
-                    .toString()
-            ).toList(Boolean.serializer().list, api, json)
+            ids.toList().chunked(50).map { list ->
+                get(
+                        EndpointBuilder("/me/$type/contains").with("ids", list.joinToString(",") { type.id(it).encodeUrl() })
+                                .toString()
+                ).toList(Boolean.serializer().list, api, json)
+            }.flatten()
         }
     }
 
@@ -148,13 +151,16 @@ class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/library/)**
      *
      * @param type The type of objects to check against (album or track)
-     * @param ids The spotify ids or uris of the objects
+     * @param ids The spotify ids or uris of the objects. Maximum **50** ids.
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun add(type: LibraryType, vararg ids: String): SpotifyRestAction<Unit> {
+        if (ids.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many ids (${ids.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many ids were provided"))
         return toAction {
-            put(EndpointBuilder("/me/$type").with("ids", ids.joinToString(",") { type.id(it).encodeUrl() }).toString())
+            ids.toList().chunked(50).forEach { list ->
+                put(EndpointBuilder("/me/$type").with("ids", list.joinToString(",") { type.id(it).encodeUrl() }).toString())
+            }
             Unit
         }
     }
@@ -189,17 +195,20 @@ class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/library/)**
      *
      * @param type The type of objects to check against (album or track)
-     * @param ids The spotify ids or uris of the objects
+     * @param ids The spotify ids or uris of the objects. Maximum **50** ids.
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
     fun remove(type: LibraryType, vararg ids: String): SpotifyRestAction<Unit> {
+        if (ids.size > 50 && !api.allowBulkRequests) throw BadRequestException("Too many ids (${ids.size}) provided, only 50 allowed", IllegalArgumentException("Bulk requests are not turned on, and too many ids were provided"))
         return toAction {
-            delete(
-                EndpointBuilder("/me/$type").with(
-                    "ids",
-                    ids.joinToString(",") { type.id(it).encodeUrl() }).toString()
-            )
+            ids.toList().chunked(50).forEach { list ->
+                delete(
+                        EndpointBuilder("/me/$type").with(
+                                "ids",
+                                list.joinToString(",") { type.id(it).encodeUrl() }).toString()
+                )
+            }
             Unit
         }
     }