spotify-web-api-java: a Java client for the Spotify Web API, with caveats

The first thing the README tells you

The README opens with a two-column table headed You and me, and the left column is not a greeting.

Spotify has a history of pushing considerable breaking changes to their API and documentation without prior notice, and Spotify is known for not responding to developers' inquiries. The README's conclusion is that this can suddenly render development on top of their platform useless, reportedly putting university projects and job applications at risk, and it asks readers to be encouraged to share their feedback with Spotify on a platform of their choice. Two links back the argument, one to Spotify's own blog post on changes to the Web API and one to a community thread about reviving the object model specification.

This is unusual to find at the top of a client library's README, and it is worth reading as the maintainer's own risk statement. The wrapper is generated from or checked against a specification, and the specification can change under it. That is not a flaw in the library, it is a property of the platform, and the library is a good place to find it stated plainly.

The practical consequence for an adopter is that the version you pin is the contract you have with the API, and that a major version bump of the library is often a reaction to an upstream change rather than a change in the library's own code. The MIGRATION.md file in the repository is the companion to that, and it is the document to read before an upgrade.

Not for Android, and the alternatives are named

The second row of that table is headed Android Developers, and it is blunt in the same register. You cannot use this library for Android app development.

The reason is not left implicit, because there is a linked explanation in the repository's issue tracker, but the practical answer is that this library is built on the assumptions of a server-side JVM application, with a dependency set and a runtime that an Android application does not have room for or cannot ship.

What the README does instead is name three alternatives: a Kotlin wrapper, another Android-specific wrapper, and Spotify's own Android SDK. The link to the discussion of why is offered so that a reader does not have to take the refusal on trust.

For a team building a service that talks to Spotify, that is exactly the right boundary to have drawn, and having it drawn in the first paragraph rather than in a footnote is a courtesy to readers. The same logic applies to other constrained runtimes: this is a library for a server, and it says so.

Maven Central for releases, Jitpack for the last commit

Installation has two routes, and the split between them is about trusting a released artifact against building the current commit.

The released artifact is on Maven Central through Sonatype, under the group se.michaelthelin.spotify:

<dependency>
  <groupId>se.michaelthelin.spotify</groupId>
  <artifactId>spotify-web-api-java</artifactId>
  <version>10.0.0</version>
</dependency>

and the Gradle form is a single implementation line. The snapshot is a different coordinate entirely, com.github.thelinmichael with a master-SNAPSHOT version, which is the jitpack.io convention, and using it means adding the jitpack repository to your build:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

That is the standard two-level setup for a Java library that wants to offer both a stable release and a build of the current commit, and the README explains the Maven repository block in the same way.

The version numbers matter here because of what the first table says. A 10.0.0 exists, the release list shows 10.0.0 alongside two release candidates from the same week, and the last push is a fortnight after the final release, so the current behaviour of the API is somewhere in the master branch rather than in the published artifact.

Request objects that execute synchronously or asynchronously

The general usage example in the README shows the shape of the client, and it is a builder followed by a request object.

SpotifyApi spotifyApi = new SpotifyApi.Builder()
        .setAccessToken("taHZ2SdB-bPA3FsK3D7ZN5npZS47cMy-IEySVEGttOhXmqaVAIo0ESvTCLjLBifhHOHOIuhFUKPW1WMDP7w6dj3MAZdWT8CLI2MkZaXbYLTeoDvXesf2eeiLYPBGdx8tIwQJKgV8XdnzH_DONk")
        .build();

A request is then built with optional parameters, in the example a market parameter, and executed either way:

final GetSomethingRequest getSomethingRequest = spotifyApi.getSomething("qKRpDADUKrFeKhFHDMdfcu")
        .market(CountryCode.SE)
        .build();

final Something something = getSomethingRequest.execute();
final Future<Something> somethingFuture = getSomethingRequest.executeAsync();

Two things are worth noticing. The optional parameters are set on the request rather than passed at execution, so the request object is a complete description of the call, which makes it easy to log, retry or queue. And the asynchronous form returns a Future, so the same request object serves both a blocking call and a non-blocking one without writing the call twice.

The builder is also where the credentials go, and the comment at the top of the example notes that an access token is needed for all requests.

Three ways to get a token, and the third one is the one you want

The authorization section points at Spotify's own authorization guide, which is the right place to start, and then explains what the API object needs.

For authorization requests, the API object requires at least the client ID and client secret of your application. When using the authorization code flow, the redirect URI is required as well, and those properties are then used automatically by the functions that depend on them.

The flows are presented in order of how much they commit you to a user. The client credentials flow is for requests that do not require permission from a specific user, it does not return a refresh token, and it is useful for simple requests such as fetching albums or searching for tracks. The authorization code flow is necessary when the requests are bound to a specific user, and it returns a refresh token that can be used to renew the access token before it expires, in two steps: the flow requires a code, which arrives as part of the redirect URI's query parameters after the user has authorised the application in a browser, and then that code is used to obtain an access token and a refresh token.

The README lists a third way to retrieve an access token, and the examples directory has a separate example directory for each flow under examples/authorization/, with a client credentials example, an authorization code URI example and an authorization code example.

For most integrations the client credentials flow is enough, and choosing it avoids the entire refresh token dance. A library that supports all three from one builder is the right shape for that decision to be a configuration choice rather than a rewrite.

Version 10, a migration guide, and a specification directory

The release history tells you where the project is. Version 10.0.0 was published on 2026-09-07, preceded by two release candidates, RC7 and RC6, on the same day, 2026-09-02. The last push was on 2026-10-15.

Two artefacts in the repository explain how a version 10 differs from a version 9. There is a MIGRATION.md, linked from the README as the migration guide for anyone upgrading from an earlier major version, and there is a spec/ directory, which is where the API surface the client is built against lives. The latter is the interesting one for the risk the first table describes, because a specification directory is the thing an upstream change would show up in first.

The rest of the tree is conventional and tidy. There is a pom.xml at the root and in the examples, a jitpack.yml for the snapshot builds, an apidocs/ directory with the generated Javadoc that is also published, a ci/ directory, an AGENTS.md, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md, a .renovaterc.json for dependency updates, and a 404.html, which is the page GitHub Pages serves for the documentation site.

The licence is MIT, with the LICENSE file at the root, and the Javadoc is credited to a named contributor, with a note of thanks to c-schuhmann for the documentation work.

Where spotify-web-api-java is the wrong choice

The first wrong-tool case is an Android application, and that is settled in the README's first screen. A mobile application has to ship a small dependency set, and a library that brings in a full client stack for a phone is the wrong shape, and the three alternatives are named for that reason.

The second is a project that cannot survive an upstream change. The first table of the README is a description of a platform that changes its API and documentation without notice, and it says the consequence is that development on top of the platform can suddenly become useless, with university projects and job applications at risk. A team whose deliverable is a demonstration or a short course should weigh that risk before making this library a dependency.

The third is a language and runtime that this library does not target. It is a Java library for the JVM, with a Maven and Gradle build and a Jitpack path, and a project on another stack would be reaching for it across a language boundary. For a service in Go, Python or TypeScript, the ecosystem wrappers for the Spotify Web API are the natural choice.

The fourth is a project that needs an API Spotify has retired or is about to retire. The wrapper can only be as current as the specification it was built from, and the maintainer's own warning is the best evidence of how quickly that can matter.

Editorial conclusion

Adopt spotify-web-api-java if you are building a server-side Java service against the Spotify Web API and you can absorb the risk of upstream changes, and pin the major version you build against. Do not adopt it for an Android application, since the README states plainly that you cannot use it there and points to other libraries, and do not adopt it if the project you are working on cannot be broken by an upstream documentation change. Before you commit, read the first table of the README and the migration guide, and check which of the three token flows your use case actually needs, since the client credentials flow alone is enough for a great many requests.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. spotify-web-api-java/spotify-web-api-java on GitHub