se.michaelthelin.spotify:spotify-web-api-java
Advanced tools
A Java client for Spotify's Web API
| Everyone – One click to help! |
|---|
| Please upvote this Spotify community issue to ensure maintenance for this repository remains possible! |
| Android Developers |
|---|
| You cannot use this library for Android app development. Have a look at adamint/spotify-web-api-kotlin, kaaes/spotify-web-api-android and Spotify's Android SDK and see why. |
This is a Java wrapper/client for the Spotify Web API.
The artifact is available through Maven Central via Sonatype. Or to use a snapshot of the latest commit you can use jitpack.io as described further down below.
Latest official release:
<dependency>
<groupId>se.michaelthelin.spotify</groupId>
<artifactId>spotify-web-api-java</artifactId>
<version>9.0.0-RC1</version>
</dependency>
Latest snapshot:
<dependency>
<groupId>com.github.thelinmichael</groupId>
<artifactId>spotify-web-api-java</artifactId>
<version>master-SNAPSHOT</version>
</dependency>
Latest official release:
implementation 'se.michaelthelin.spotify:spotify-web-api-java:9.0.0-RC1'
Latest snapshot:
implementation 'com.github.thelinmichael:spotify-web-api-java:master-SNAPSHOT'
In order to use Jitpack you need to add their repository to your pom.xml:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
See this project's Javadoc.
A huge thanks to c-schuhmann for his amazing work on the documentation!
// For all requests an access token is needed
SpotifyApi spotifyApi = new SpotifyApi.Builder()
.setAccessToken("taHZ2SdB-bPA3FsK3D7ZN5npZS47cMy-IEySVEGttOhXmqaVAIo0ESvTCLjLBifhHOHOIuhFUKPW1WMDP7w6dj3MAZdWT8CLI2MkZaXbYLTeoDvXesf2eeiLYPBGdx8tIwQJKgV8XdnzH_DONk")
.build();
// Create a request object with the optional parameter "market"
final GetSomethingRequest getSomethingRequest = spotifyApi.getSomething("qKRpDADUKrFeKhFHDMdfcu")
.market(CountryCode.SE)
.build();
void getSomething_Sync() {
try {
// Execute the request synchronous
final Something something = getSomethingRequest.execute();
// Print something's name
System.out.println("Name: " + something.getName());
} catch (Exception e) {
System.out.println("Something went wrong!\n" + e.getMessage());
}
}
void getSomething_Async() {
try {
// Execute the request asynchronous
final Future<Something> somethingFuture = getSomethingRequest.executeAsync();
// Do other things...
// Wait for the request to complete
final Something something = somethingFuture.get();
// Print something's name
System.out.println("Name: " + something.getName());
} catch (Exception e) {
System.out.println("Something went wrong!\n" + e.getMessage());
}
}
Please see Spotify's Authorization Guide too!
For authorization requests the API object requires at least to have your application's client ID and client secret set as its properties. When using the authorization code flow, the application's redirect URI is required too. Those properties will then be automatically used by functions that depend on them.
SpotifyApi spotifyApi = new SpotifyApi.Builder()
.setClientId("<your_client_id>")
.setClientSecret("<your_client_secret>")
.setRedirectUri("<your_redirect_uri>")
.build();
There are three ways to retrieving an access token:
Use the client credentials flow when the requests don't require permission from a specific user. This flow doesn't return a refresh token and is useful for simple requests, like fetching albums or searching for tracks.
Example: ClientCredentialsExample.java
Using the authorization code flow to retrieve an access token is necessary if the requests are bound to a specific user. Using this flow returns a refresh token, which can be used to renew the access token before it expires. This is how it works:
The authorization code flow requires a code, which is part of the redirectUri's query parameters when the user has
opened a custom URL in a browser and authorized the application.
Example: AuthorizationCodeUriExample.java
When the code has been retrieved, it can be used in another request to get an access token as well as a refresh token.
Example: AuthorizationCodeExample.java
Now, the refresh token in turn can be used in a loop to retrieve new access and refresh tokens.
Example: AuthorizationCodeRefreshExample.java
When you've fetched an access and refresh token, you have to add them to your API properties for automatic usage in requests. The implementer has to handle the access token's expiration.
spotifyApi
.setAccessToken("<your_access_token>")
.setRefreshToken("<your_refresh_token>")
.build();
The authorization code flow with PKCE is quite like the Authorization Code Flow except that no client secret is necessary (therefore, it is a good option for mobile and desktop applications). Instead, your application should generate a code verifier and a code challenge before each authentication request.
The code verifier is a cryptographically random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes. To generate the code challenge, your app should hash the code verifier using the SHA256 algorithm. Then, base64url encode the hash that you generated.
This flow provides your app with an access token which can be refreshed, too. The steps are similar as above:
The authorization code flow with PKCE requires a code, which is part of the redirectUri's query parameters when the user has
opened a custom URL in a browser and authorized the application. The code challenge is supplied to this request as a query parameter.
Example: AuthorizationCodePKCEUriExample.java
When the code has been retrieved, it can be used in another request to get an access token as well as a refresh token. The code verifier is supplied to this request a query parameter.
Example: AuthorizationCodePKCEExample.java
Now, the refresh token in turn can be used in a loop to retrieve new access and refresh tokens.
When you have fetched an access and refresh token, you have to add them to your API properties for automatic usage in requests. The implementer must handle the access token's expiration. The refresh token can be exchanged for an access token only once, after which it becomes invalid.
Albums
Artists
Browse
Episodes
Follow
Library
Personalization
Player
Playlists
Search
Shows
Tracks
User's Profile
See CONTRIBUTING.md.
mvn clean installmvn clean testRequirements: Java, Maven.
This project's main Java package is divided into four sections:
Those unit-tested parts are connected through various classes that make the API accessible for other Java projects. You can find details about specific parts or single classes in the sections below.
src/main/java/se.michaelthelin.spotify/enums/
Enumerations allow elements to "be of a type" and limit them to a known value set. They are currently not specified in a unique place, but are rather scrambled across the online reference. Thus, the reference only allows for construction of enum classes from this sparse information.
src/main/java/se.michaelthelin.spotify/exceptions/
Exceptions are thrown when errors occur. They are following RFC-specified HTTP status codes and are packed with a more detailed error description.
src/main/java/se.michaelthelin.spotify/model_objects/
The model objects are entities that form the API's responses in arranged formats. They are mostly specified in the Web API Object Model and in the Web API Authorization Guide. Though, unreferenced model objects exist. This project subdivides those into...
Java classes representing those model objects include private instance variables, a private constructor, but public getter methods as well as an embedded...
createModelObject method.src/main/java/se.michaelthelin.spotify/requests/
The request classes mirror the structure of Spotify's Web Api endpoints. They are divided into several categories like
authorization, data/albums or data/tracks. They must extend from AbstractDataRequest and contain an
implementation of the request's execute method. They have to embed a builder class too, enabling dynamic request
creation.
src/test/java/se.michaelthelin.spotify/
Unit tests ensure that implemented features work. This project's unit tests are implemented with JUnit and mockito for mocking.
src/test/fixtures/
Fixtures are JSON files that represent the data returned from the API server. We use the examples directly provided by the Web API Endpoint Reference with minor tweaks. Tweaks are needed because the reference sometimes contains invalid data examples.
FAQs
A Java client for Spotify's Web API
We found that se.michaelthelin.spotify:spotify-web-api-java demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.