spotify-web-api-java · dargmuesli · Apr 29, 2026 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IAlbum.java b/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IAlbum.java
@@ -0,0 +1,99 @@
+package se.michaelthelin.spotify.model_objects.interfaces;
+
+import se.michaelthelin.spotify.enums.AlbumType;
+import se.michaelthelin.spotify.enums.ModelObjectType;
+import se.michaelthelin.spotify.enums.ReleaseDatePrecision;
+import se.michaelthelin.spotify.model_objects.specification.Album;
+import se.michaelthelin.spotify.model_objects.specification.AlbumSimplified;
+import se.michaelthelin.spotify.model_objects.specification.ArtistSimplified;
+import se.michaelthelin.spotify.model_objects.specification.ExternalUrl;
+import se.michaelthelin.spotify.model_objects.specification.Image;
+import se.michaelthelin.spotify.model_objects.special.AlbumSimplifiedSpecial;
+
+/**
+ * Represents the common properties of Spotify Album objects (full and simplified).
+ *
+ * <p>This interface provides a common base for {@link Album}, {@link AlbumSimplified},
+ * and {@link AlbumSimplifiedSpecial} objects.
+ */
+public interface IAlbum {
+  /**
+   * Get the type of the album.
+   *
+   * @return The {@link AlbumType}.
+   */
+  AlbumType getAlbumType();
+
+  /**
+   * Get the artists of the album.
+   *
+   * @return An array of {@link ArtistSimplified} objects.
+   */
+  ArtistSimplified[] getArtists();
+
+  /**
+   * Get the external URLs of the album. <br>
+   * Example: <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify-URL</a>
+   *
+   * @return An {@link ExternalUrl} object.
+   */
+  ExternalUrl getExternalUrls();
+
+  /**
+   * Get the full Spotify Web API endpoint URL of the album.
+   *
+   * @return A Spotify Web API endpoint URL.
+   */
+  String getHref();
+
+  /**
+   * Get the Spotify ID of the album.
+   *
+   * @return A <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify album ID</a>.
+   */
+  String getId();
+
+  /**
+   * Get the album cover art of the album in different sizes.
+   *
+   * @return An array of {@link Image} objects.
+   */
+  Image[] getImages();
+
+  /**
+   * Get the name of the album.
+   *
+   * @return Album name.
+   */
+  String getName();
+
+  /**
+   * Get the release date of the album with the highest precision available.
+   *
+   * @return The release date of the album.
+   */
+  String getReleaseDate();
+
+  /**
+   * Get the precision of the albums release date. This is needed when the exact release day of an album is not known.
+   *
+   * @return The precision of the albums release date.
+   */
+  ReleaseDatePrecision getReleaseDatePrecision();
+
+  /**
+   * Get the model object type. In this case "album".
+   *
+   * @return A {@link ModelObjectType}.
+   */
+  ModelObjectType getType();
+
+  /**
+   * Get the Spotify URI of the album.
+   *
+   * @return <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify album URI</a>.
+   */
+  String getUri();
+}
+
+
diff --git a/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IArtist.java b/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IArtist.java
@@ -0,0 +1,59 @@
+package se.michaelthelin.spotify.model_objects.interfaces;
+
+import se.michaelthelin.spotify.enums.ModelObjectType;
+import se.michaelthelin.spotify.model_objects.specification.Artist;
+import se.michaelthelin.spotify.model_objects.specification.ArtistSimplified;
+import se.michaelthelin.spotify.model_objects.specification.ExternalUrl;
+
+/**
+ * Represents the common properties of Spotify Artist objects (full and simplified).
+ *
+ * <p>This interface provides a common base for {@link Artist} and
+ * {@link ArtistSimplified} objects.
+ */
+public interface IArtist {
+  /**
+   * Get the external URLs of the artist. <br>
+   * Example: <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify-URL</a>
+   *
+   * @return An {@link ExternalUrl} object.
+   */
+  ExternalUrl getExternalUrls();
+
+  /**
+   * Get the full Spotify Web API endpoint URL of the artist.
+   *
+   * @return A Spotify Web API endpoint URL.
+   */
+  String getHref();
+
+  /**
+   * Get the Spotify ID of the artist.
+   *
+   * @return A <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify artist ID</a>.
+   */
+  String getId();
+
+  /**
+   * Get the name of the artist.
+   *
+   * @return Artist name.
+   */
+  String getName();
+
+  /**
+   * Get the model object type. In this case "artist".
+   *
+   * @return A {@link ModelObjectType}.
+   */
+  ModelObjectType getType();
+
+  /**
+   * Get the Spotify URI of the artist.
+   *
+   * @return <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify artist URI</a>.
+   */
+  String getUri();
+}
+
+
diff --git a/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IEpisode.java b/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IEpisode.java
@@ -0,0 +1,91 @@
+package se.michaelthelin.spotify.model_objects.interfaces;
+
+import se.michaelthelin.spotify.enums.ReleaseDatePrecision;
+import se.michaelthelin.spotify.model_objects.IPlaylistItem;
+import se.michaelthelin.spotify.model_objects.specification.Episode;
+import se.michaelthelin.spotify.model_objects.specification.EpisodeSimplified;
+import se.michaelthelin.spotify.model_objects.specification.Image;
+import se.michaelthelin.spotify.model_objects.specification.ResumePoint;
+
+/**
+ * Represents the common properties of Spotify Episode objects (full and simplified).
+ *
+ * <p>This interface extends {@link IPlaylistItem} and provides a common base for
+ * {@link Episode} and
+ * {@link EpisodeSimplified}
+ * objects.
+ */
+public interface IEpisode extends IPlaylistItem {
+  /**
+   * Get a link to a 30 second preview (MP3 format) of the episode. {@code null} if not available.
+   *
+   * @return A link to a 30 second preview (MP3 format) of the episode. {@code null} if not available.
+   */
+  String getAudioPreviewUrl();
+
+  /**
+   * Get a description of the episode.
+   *
+   * @return The description of the episode.
+   */
+  String getDescription();
+
+  /**
+   * Check whether the episode is explicit or not.
+   *
+   * @return Whether or not the episode has explicit content ({@code true} = yes it does; {@code false} = no it does not
+   *         <b>OR</b> unknown).
+   */
+  Boolean getExplicit();
+
+  /**
+   * Get the cover art for the episode in various sizes, widest first.
+   *
+   * @return An array of {@link Image} objects.
+   */
+  Image[] getImages();
+
+  /**
+   * Check whether the episode is hosted outside of Spotify's CDN.
+   *
+   * @return True if the episode is hosted outside of Spotify's CDN.
+   */
+  Boolean getExternallyHosted();
+
+  /**
+   * Check whether the episode is playable in the given market.
+   *
+   * @return True if the episode is playable in the given market. Otherwise false.
+   */
+  Boolean getPlayable();
+
+  /**
+   * Get a list of the languages used in the episode, identified by their ISO 639 code.
+   *
+   * @return An array of <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 alpha-2 country codes</a>.
+   */
+  String[] getLanguages();
+
+  /**
+   * Get the date the episode was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".
+   *
+   * @return The release date of the episode.
+   */
+  String getReleaseDate();
+
+  /**
+   * Get the precision with which the release date is known.
+   *
+   * @return A {@link ReleaseDatePrecision} object.
+   */
+  ReleaseDatePrecision getReleaseDatePrecision();
+
+  /**
+   * Get the user's most recent position in the episode. Set if the supplied access token is a user token and has the scope {@code user-read-playback-position}.
+   *
+   * @return A {@link ResumePoint} object.
+   */
+  ResumePoint getResumePoint();
+}
+
+
diff --git a/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IHasTotal.java b/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IHasTotal.java
@@ -0,0 +1,17 @@
+package se.michaelthelin.spotify.model_objects.interfaces;
+
+/**
+ * Represents an object that has a total count.
+ * <p>
+ * This interface is implemented by objects that provide a total count of items,
+ * such as playlists or other paging objects.
+ */
+public interface IHasTotal {
+  /**
+   * Get the total count.
+   *
+   * @return The total count of items
+   */
+  Integer getTotal();
+}
+
diff --git a/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IPlaylist.java b/src/main/java/se/michaelthelin/spotify/model_objects/interfaces/IPlaylist.java
@@ -0,0 +1,128 @@
+package se.michaelthelin.spotify.model_objects.interfaces;
+
+import se.michaelthelin.spotify.enums.ModelObjectType;
+import se.michaelthelin.spotify.model_objects.specification.ExternalUrl;
+import se.michaelthelin.spotify.model_objects.specification.Image;
+import se.michaelthelin.spotify.model_objects.specification.Playlist;
+import se.michaelthelin.spotify.model_objects.specification.PlaylistSimplified;
+import se.michaelthelin.spotify.model_objects.specification.User;
+
+/**
+ * Represents the common properties of Spotify Playlist objects (full and simplified).
+ *
+ * <p>This interface provides a common base for {@link Playlist} and
+ * {@link PlaylistSimplified} objects.
+ *
+ * @param <T> The concrete type of the items/tracks metadata object. {@link Playlist} uses
+ *            {@link se.michaelthelin.spotify.model_objects.specification.Paging} and
+ *            {@link PlaylistSimplified} uses
+ *            {@link se.michaelthelin.spotify.model_objects.miscellaneous.PlaylistTracksInformation}.
+ */
+public interface IPlaylist<T extends IHasTotal> {
+  /**
+   * Check whether the owner allows other users to modify the playlist.
+   *
+   * @return {@code true} if other users are allowed to modify the playlist, {@code false} otherwise.
+   * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/playlists">
+   *      Spotify: Working With Playlists</a>
+   */
+  Boolean getIsCollaborative();
+
+  /**
+   * Get the description of the playlist.
+   *
+   * @return The playlist description. Only returned for modified, verified playlists, otherwise {@code null}.
+   */
+  String getDescription();
+
+  /**
+   * Get the external URLs of the playlist. <br>
+   * Example: Spotify-URL.
+   *
+   * @return Known external URLs for this playlist.
+   */
+  ExternalUrl getExternalUrls();
+
+  /**
+   * Get the full Spotify API endpoint url of the playlist.
+   *
+   * @return A link to the Web API endpoint providing full details of the playlist.
+   */
+  String getHref();
+
+  /**
+   * Get the <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify ID</a>
+   * of a playlist.
+   *
+   * @return The Spotify ID for the playlist.
+   */
+  String getId();
+
+  /**
+   * Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in
+   * descending order. <br>
+   * <b>Note:</b> If returned, the source URL for the image is temporary and will expire in less than a day.
+   *
+   * @return An array of images in different sizes.
+   * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/playlists">
+   *      Spotify: Working With Playlists</a>
+   */
+  Image[] getImages();
+
+  /**
+   * Get the name of a playlist.
+   *
+   * @return Playlist name.
+   */
+  String getName();
+
+  /**
+   * Get the owners user object of a playlist.
+   *
+   * @return A user object.
+   */
+  User getOwner();
+
+  /**
+   * Check whether a playlist is available in public or is private.
+   *
+   * @return {@code true} the playlist is public, {@code false} the playlist is private, {@code null}
+   *         the playlist status is not relevant.
+   * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/playlists">
+   *      Spotify: Working With Playlists</a>
+   */
+  Boolean getIsPublicAccess();
+
+  /**
+   * Get information about the items in the playlist. The concrete type depends on the specific playlist object type.
+   *
+   * @return Item information containing total count.
+   */
+  T getItems();
+
+  /**
+   * Get the snapshot ID, the version identifier for the current playlist. Can be supplied in other requests to target
+   * a specific playlist version.
+   *
+   * @return The version identifier for the current playlist.
+   * @see se.michaelthelin.spotify.requests.data.playlists.RemoveItemsFromPlaylistRequest
+   */
+  String getSnapshotId();
+
+  /**
+   * Get the model object type. In this case "playlist".
+   *
+   * @return The object type: "playlist"
+   */
+  ModelObjectType getType();
+
+  /**
+   * Get the <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify URI</a>
+   * of a playlist.
+   *
+   * @return Spotify playlist URI.
+   */
+  String getUri();
+}
+
+