You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To use the latest snapshot instead, you must add the Jitpack repository
35
+
To use the latest snapshot instead, you must add the Jitpack repository as well
41
36
```
42
37
repositories {
43
-
maven { url 'https://jitpack.io' }
38
+
maven { url 'https://jitpack.io' }
39
+
jcenter()
44
40
}
45
41
```
46
42
Then, you can use the following:
@@ -50,21 +46,39 @@ dependencies {
50
46
}
51
47
```
52
48
49
+
### Maven
50
+
```
51
+
<dependency>
52
+
<groupId>com.adamratzman</groupId>
53
+
<artifactId>spotify-api-kotlin</artifactId>
54
+
<version>2.2.0</version>
55
+
</dependency>
56
+
57
+
<repository>
58
+
<id>jcenter</id>
59
+
<name>jcenter-bintray</name>
60
+
<url>http://jcenter.bintray.com</url>
61
+
</repository>
62
+
```
63
+
53
64
#### Android
54
-
This library should work out of the box on Android.
65
+
This library will work out of the box on Android.
55
66
56
67
## Documentation
57
-
The `spotify-web-api-kotlin`KDocs are hosted at https://adamint.github.io/spotify-web-api-kotlin
68
+
The `spotify-web-api-kotlin`JavaDocs are hosted at https://adamint.github.io/spotify-web-api-kotlin
58
69
59
70
## Creating a SpotifyAPI or SpotifyClientAPI object
60
71
In order to use the methods in this library, you must create either a `SpotifyAPI` or `SpotifyClientAPI` object using their respective exposed builders. Client-specific methods are unable to be accessed with the generic SpotifyAPI, rather you must create an instance of the Client API.
61
72
62
73
### SpotifyAPI
63
-
The SpotifyAPI `Token` automatically regenerates when needed.
64
-
To build it, you must pass the application id and secret.
74
+
By default, the SpotifyAPI `Token` automatically regenerates when needed. This can be changed
75
+
through the `automaticRefresh` parameter in all builders.
76
+
77
+
To build a new `SpotifyAPI`, you must pass the application id and secret.
78
+
65
79
```kotlin
66
-
importcom.adamratzman.spotify.main.SpotifyScope
67
-
importcom.adamratzman.spotify.main.spotifyApi
80
+
importcom.adamratzman.spotify.SpotifyScope
81
+
importcom.adamratzman.spotify.spotifyApi
68
82
69
83
spotifyApi {
70
84
credentials {
@@ -75,25 +89,25 @@ spotifyApi {
75
89
```
76
90
*Note:* You are **unable** to use any client endpoint without authenticating with the methods below.
77
91
78
-
### SpotifyClientAPI
79
-
All endpoints inside `SpotifyAPI` can be accessed within the `SpotifyClientAPI`.
92
+
#### SpotifyClientAPI
93
+
The `SpotifyClientAPI` is a superset of `SpotifyAPI`.
94
+
80
95
Its automatic refresh is available *only* when building with
81
-
an authorization code or a `Token` object. Otherwise, it will expire `Token#expires_in` seconds after creation.
96
+
an authorization code or a `Token` object. Otherwise, it will expire `Token.expiresIn` seconds after creation.
82
97
83
98
You have two options when building the Client API.
84
-
1. You can use [Implicit Grant access tokens](https://developer.spotify.com/web-api/authorization-guide/#implicit_grant_flow) with
85
-
`Builder.buildToken(token: String)`. However, this is a one-time token that cannot be refreshed.
86
-
2. You can use the [Authorization code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow). We provide a method
87
-
with `Builder.buildAuthCode(code: String, automaticRefresh: Boolean)`to generate the flow url with Builder.getAuthUrl(vararg spotifyScopes: Scope), allowing you to request specific
88
-
spotifyScopes. This library does not provide a method to retrieve the code from your
89
-
callback URL. You must implement that with a web server. This method allows you
90
-
to choose whether to use automatic token refresh.
99
+
1. You can use [Implicit Grant access tokens](https://developer.spotify.com/web-api/authorization-guide/#implicit_grant_flow) by
100
+
setting the value of `tokenString` in the builder `authentication` block. However, this is a one-time token that cannot be refreshed.
101
+
2. You can use the [Authorization code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow) by
102
+
setting the value of `authorizationCode` in a builder. You may generate an authentication flow url allowing you to request specific
103
+
Spotify scopes using the `getAuthorizationUrl` method in any builder. This library does not provide a method to retrieve the code from your
104
+
callback URL; you must implement that with a web server.
91
105
92
106
## What is the SpotifyRestAction class?
93
-
I wanted users of this library to have as much flexibility as possible. This
94
-
includes options for asynchronous and blocking execution in all endpoints. However,
107
+
Abstracting requests into a `SpotifyRestAction` class allows for a lot of flexibility in sending and receiving requests.
108
+
This class includes options for asynchronous and blocking execution in all endpoints. However,
95
109
due to this, you **must** call one of the provided methods in order for the call
96
-
to execute! The `SpotifyRestAction` provides four methods for use: 1 blocking and 3 async.
110
+
to execute! The `SpotifyRestAction` provides many methods for use, including blocking and asynchronous ones. For example,
97
111
-`complete()` blocks the current thread and returns the result
98
112
-`queue()` executes and immediately returns
99
113
-`queue(consumer: (T) -> Unit)` executes the provided callback as soon as the request
@@ -131,7 +145,7 @@ Just like with PagingObjects, you can get the next page of items with `getNext`.
131
145
provided implementation of `after` in this library. You will need to do it yourself, if necessary.
132
146
133
147
#### LinkedResults
134
-
Some endpoints, like `PlaylistsAPI.getPlaylistTracks`, return a LinkedResult, which is a simple wrapper around the
148
+
Some endpoints, like `PlaylistAPI.getPlaylistTracks`, return a LinkedResult, which is a simple wrapper around the
135
149
list of objects. With this, we have access to its Spotify API url (with `href`), and we provide simple methods to parse
136
150
that url.
137
151
@@ -140,31 +154,31 @@ For obvious reasons, in most cases, making asynchronous requests via `queue` or
140
154
the synchronous format is also shown.
141
155
142
156
```kotlin
143
-
importcom.adamratzman.spotify.main.SpotifyScope
144
-
importcom.adamratzman.spotify.main.spotifyApi
157
+
importcom.adamratzman.spotify.SpotifyScope
158
+
importcom.adamratzman.spotify.spotifyApi
145
159
146
-
valspotifyApi= spotifyApi {
160
+
valapi= spotifyApi {
147
161
credentials {
148
162
clientId ="YOUR_CLIENT_ID"
149
163
clientSecret ="YOUR_CLIENT_SECRET"
150
164
}
151
165
}.buildCredentialed()
152
166
153
167
// block and print out the names of the twenty most similar songs to the search
154
-
spotifyApi.search.searchTrack("Début de la Suite").complete().map { it.name }.joinToString().let { println(it) }
168
+
println(api.search.searchTrack("Début de la Suite").complete().map { it.name }.joinToString())
155
169
156
170
// now, let's do it asynchronously
157
-
spotifyApi.search.searchTrack("Début de la Suite").queue { it.map { it.name }.joinToString().let { println(it) } }
171
+
api.search.searchTrack("Début de la Suite").queue { println(it.map { it.name }.joinToString()) }
158
172
159
-
// simple, right? what about if we want to print ou the featured playlists message from the "Overview" tab?
1. `followingUsers` returns an ordered List of Booleans representing if the user follows the specified users
250
264
2. `followingArtists` returns an ordered List of Booleans representing if the user follows the specified artists
251
265
3. `getFollowedArtists` returns a [Cursor-Based Paging Object](https://developer.spotify.com/web-api/object-model/#cursor-based-paging-object) of followed Artists.
@@ -257,7 +271,7 @@ links provided for each API below
257
271
9. `unfollowPlaylist` unfollows the specified playlist. Returns nothing
0 commit comments