add common interfaces by fm-sys · Pull Request #457 · spotify-web-api-java/spotify-web-api-java

fm-sys · 2026-04-13T07:55:56Z

I'm working on a project, where I'm sometimes getting a PlaylistSimplified and sometimes a Playlist. As I only need the basic properties, it would save me a lot of boilerplate code if I could downcast both classes to IPlaylist instead of writing my own conversion methods and model classes.

Therefore, this pull request introduces new interfaces to unify the representation of Spotify model objects (Album, Artist, Playlist, Show, Episode, and Track), and updates the corresponding model classes to implement these interfaces. This especially benefits applications implementing this library by providing common interfaces for full and simplified versions of model objects.

I've added no tests, as interfaces only provide the contract, not the implementation, and the model class specific implementations are already tested.

The change is done in a way it shouldn't break any code of existing applications. I've targeted the beta branch and would be happy if this PR could be included in the final v10 release.

fm-sys · 2026-04-13T13:11:12Z

Right now, I've placed all new common interfaces in an interfaces subfolder. We could move IModelObject.java and IPlaylistItem.java in there as well for consistency (there are breaking changes in v10 anyway). Or don't do it for backward compatibility. I'm undecided about this one, so let me know :)

codecov · 2026-04-13T13:35:06Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 49.84%. Comparing base (a069569) to head (557f20d).

Additional details and impacted files

@@            Coverage Diff            @@
##               beta     #457   +/-   ##
=========================================
  Coverage     49.84%   49.84%           
  Complexity      582      582           
=========================================
  Files           243      243           
  Lines          8626     8626           
  Branches       1054     1054           
=========================================
  Hits           4300     4300           
  Misses         3526     3526           
  Partials        800      800

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

This PR introduces a set of shared model interfaces (Album, Artist, Playlist, Show, Episode, Track) so callers can treat full and simplified Spotify model objects uniformly, and updates the corresponding model classes to implement those interfaces.

Changes:

Added new common interfaces under se.michaelthelin.spotify.model_objects.interfaces (e.g., IPlaylist, ITrack, etc.).
Updated full + simplified specification model classes (and AlbumSimplifiedSpecial) to implement the new interfaces.
Enabled simplified Track/Episode to be treated as playlist items via ITrack/IEpisode extending IPlaylistItem.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/main/java/se/michaelthelin/spotify/model_objects/specification/TrackSimplified.java	Implements `ITrack` to unify simplified Track usage.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Track.java	Implements `ITrack` to unify full Track usage.
src/main/java/se/michaelthelin/spotify/model_objects/specification/ShowSimplified.java	Implements `IShow` for common Show access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Show.java	Implements `IShow` for common Show access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/PlaylistSimplified.java	Implements `IPlaylist` for common Playlist access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Playlist.java	Implements `IPlaylist` for common Playlist access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/EpisodeSimplified.java	Implements `IEpisode` for common Episode access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Episode.java	Implements `IEpisode` for common Episode access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/ArtistSimplified.java	Implements `IArtist` for common Artist access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Artist.java	Implements `IArtist` for common Artist access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/AlbumSimplified.java	Implements `IAlbum` for common Album access.
src/main/java/se/michaelthelin/spotify/model_objects/specification/Album.java	Implements `IAlbum` for common Album access.
src/main/java/se/michaelthelin/spotify/model_objects/special/AlbumSimplifiedSpecial.java	Implements `IAlbum` to include the “special” simplified album in the common contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/ITrack.java	New interface defining shared Track contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IShow.java	New interface defining shared Show contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IPlaylist.java	New interface defining shared Playlist contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IEpisode.java	New interface defining shared Episode contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IArtist.java	New interface defining shared Artist contract.
src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IAlbum.java	New interface defining shared Album contract.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

fm-sys · 2026-04-13T13:41:42Z

IEpisode and ITrack furthermore share similarities which could be unified inside IPlaylistItem, however they currently do not share the same method names:

getAudioPreviewUrl vs getPreviewUrl
getExplicit vs getIsExplicit
getPlayable vs getIsPlayable

However, renaming these would also be a breaking change…

dargmuesli · 2026-04-13T13:47:26Z

As this PR targets beta, breaking changes are ok. As long as this repo's source code stays in sync with Spotify's api docs, I'm fine with such changes!

dargmuesli

Just rerequest me as reviewer once not draft anymore 🙌

fm-sys · 2026-04-13T20:20:14Z

As long as this repo's source code stays in sync with Spotify's api docs, I'm fine with such changes!

@dargmuesli thanks for your reply :)

Let me ask a follow up question:

In the Spotify docs, it's explicit and is_playable for Episode and Track, while one uses preview_url and the other uses audio_preview_url.

Track.java currently uses getIsPlayable, getIsExplicit, getPreviewUrl, Episodes the other one.

Personally I would say, let's use the ones we already have for Tracks as they are probably used more and rename the Episode counterparts (although this would not be exactly in line with the official Spotify API doc). Exactly sticking to the API would also mean that we cannot have a common preview URL method.

If we want to rename, we could either keep the old method names as well and mark them as depreciated or remove directly.

But as I don't really like the felling to break code intentionally and to do not block the remaining PR, I'm also fine with not unifying these methods for now.

So let me know whether you have a preference, despite that the PR would be ready for review.

add common interfaces

557f20d

fm-sys force-pushed the common-interfaces branch from 9bef08e to 557f20d Compare April 13, 2026 13:30

dargmuesli requested review from Copilot and dargmuesli April 13, 2026 13:33

Copilot started reviewing on behalf of dargmuesli April 13, 2026 13:34 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

apply copilot review suggestion

fcf3d08

fm-sys marked this pull request as draft April 13, 2026 14:39

dargmuesli reviewed Apr 13, 2026

View reviewed changes

fm-sys force-pushed the common-interfaces branch from 9d14a94 to d6700e3 Compare April 13, 2026 20:08

add getItems to IPlaylist to allow querying number of total tracks

01f413e

fm-sys force-pushed the common-interfaces branch from d6700e3 to 01f413e Compare April 13, 2026 20:10

fm-sys marked this pull request as ready for review April 13, 2026 20:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add common interfaces#457

add common interfaces#457
fm-sys wants to merge 3 commits intospotify-web-api-java:betafrom
fm-sys:common-interfaces

fm-sys commented Apr 13, 2026

Uh oh!

fm-sys commented Apr 13, 2026 •

edited

Loading

Uh oh!

codecov bot commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fm-sys commented Apr 13, 2026

Uh oh!

dargmuesli commented Apr 13, 2026

Uh oh!

dargmuesli left a comment

Uh oh!

fm-sys commented Apr 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

fm-sys commented Apr 13, 2026

Uh oh!

fm-sys commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Apr 13, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fm-sys commented Apr 13, 2026

Uh oh!

dargmuesli commented Apr 13, 2026

Uh oh!

dargmuesli left a comment

Choose a reason for hiding this comment

Uh oh!

fm-sys commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fm-sys commented Apr 13, 2026 •

edited

Loading

fm-sys commented Apr 13, 2026 •

edited

Loading