refactor(playlists): deprecate legacy builders and reorder deprecatio…

…n notes
dargmuesli · Sep 7, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026
commit 2eae502a7400db62a38deb97386ae66a555fa22e
diff --git a/src/main/java/se/michaelthelin/spotify/SpotifyApi.java b/src/main/java/se/michaelthelin/spotify/SpotifyApi.java
@@ -1622,7 +1622,6 @@ public AddItemsToPlaylistRequest.Builder addItemsToPlaylist(String playlist_id,
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Add items to a playlist (deprecated endpoint).
    * <p>
    * <b>Note:</b> If you want to add a large number of items (&gt;50), use {@link #addItemsToPlaylistDeprecated(String, JsonArray)} to not exceed
@@ -1631,6 +1630,7 @@ public AddItemsToPlaylistRequest.Builder addItemsToPlaylist(String playlist_id,
    * @param uris        URIs of the tracks or episodes to add. Maximum: 100 item URIs.
    * @return An {@link AddItemsToPlaylistDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #addItemsToPlaylist(String, String[])} instead.
    */
   @Deprecated
   public AddItemsToPlaylistDeprecatedRequest.Builder addItemsToPlaylistDeprecated(String playlist_id, String[] uris) {
@@ -1641,13 +1641,13 @@ public AddItemsToPlaylistDeprecatedRequest.Builder addItemsToPlaylistDeprecated(
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Add items to a playlist (deprecated endpoint).
    *
    * @param playlist_id The playlists ID.
    * @param uris        URIs of the tracks or episodes to add. Maximum: 100 item URIs.
    * @return An {@link AddItemsToPlaylistDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #addItemsToPlaylist(String, JsonArray)} instead.
    */
   @Deprecated
   public AddItemsToPlaylistDeprecatedRequest.Builder addItemsToPlaylistDeprecated(String playlist_id, JsonArray uris) {
@@ -1764,12 +1764,12 @@ public GetPlaylistItemsRequest.Builder getPlaylistItems(String playlist_id) {
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Get full details of the tracks or episodes of a playlist owned by a Spotify user (deprecated endpoint).
    *
    * @param playlist_id The playlists ID.
    * @return A {@link GetPlaylistItemsDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #getPlaylistItems(String)} instead.
    */
   @Deprecated
   public GetPlaylistItemsDeprecatedRequest.Builder getPlaylistItemsDeprecated(String playlist_id) {
@@ -1795,13 +1795,13 @@ public RemovePlaylistItemsRequest.Builder removePlaylistItems(
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Delete items from a playlist (deprecated endpoint).
    *
    * @param playlist_id The playlists ID.
    * @param tracks      URIs of the items to remove. Maximum: 100 track or episode URIs.
    * @return A {@link RemovePlaylistItemsDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #removePlaylistItems(String, JsonArray)} instead.
    */
   @Deprecated
   public RemovePlaylistItemsDeprecatedRequest.Builder removePlaylistItemsDeprecated(
@@ -1835,7 +1835,6 @@ public UpdatePlaylistsItemsReorderRequest.Builder updatePlaylistsItemsReorder(St
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Reorder an item or a group of items in a playlist (deprecated endpoint). <br><br>
    *
    * @param playlist_id   The Spotify ID for the playlist.
@@ -1844,6 +1843,7 @@ public UpdatePlaylistsItemsReorderRequest.Builder updatePlaylistsItemsReorder(St
    *                      playlist, simply set insert_before to the position after the last item.
    * @return A {@link UpdatePlaylistsItemsReorderDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #updatePlaylistsItemsReorder(String, int, int)} instead.
    */
   @Deprecated
   public UpdatePlaylistsItemsReorderDeprecatedRequest.Builder updatePlaylistsItemsReorderDeprecated(String playlist_id, int range_start, int insert_before) {
@@ -1885,13 +1885,13 @@ public UpdatePlaylistsItemsReplaceRequest.Builder updatePlaylistsItemsReplace(St
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Replace items in a playlist (deprecated endpoint).
    *
    * @param playlist_id The playlists ID.
    * @param uris        URIs of the items to set. Maximum: 100 track or episode URIs.
    * @return A {@link UpdatePlaylistsItemsReplaceDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #updatePlaylistsItemsReplace(String, String[])} instead.
    */
   @Deprecated
   public UpdatePlaylistsItemsReplaceDeprecatedRequest.Builder updatePlaylistsItemsReplaceDeprecated(String playlist_id, String[] uris) {
@@ -1902,13 +1902,13 @@ public UpdatePlaylistsItemsReplaceDeprecatedRequest.Builder updatePlaylistsItems
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Replace items in a playlist (deprecated endpoint).
    *
    * @param playlist_id The playlists ID.
    * @param uris        URIs of the items to add. Maximum: 100 track or episode URIs.
    * @return A {@link UpdatePlaylistsItemsReplaceDeprecatedRequest.Builder}.
    * @see <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify: URLs &amp; IDs</a>
+   * @deprecated Use {@link #updatePlaylistsItemsReplace(String, JsonArray)} instead.
    */
   @Deprecated
   public UpdatePlaylistsItemsReplaceDeprecatedRequest.Builder updatePlaylistsItemsReplaceDeprecated(String playlist_id, JsonArray uris) {

diff --git a/...se/michaelthelin/spotify/requests/data/playlists/AddItemsToPlaylistDeprecatedRequest.java b/...se/michaelthelin/spotify/requests/data/playlists/AddItemsToPlaylistDeprecatedRequest.java
@@ -11,15 +11,15 @@
 import java.io.IOException;
 
 /**
- * @deprecated Use the new endpoints instead.
  * Add one or more items to a user's playlist.
+ *
+ * @deprecated Use {@link AddItemsToPlaylistRequest} instead.
  */
 @Deprecated
 @JsonDeserialize(builder = AddItemsToPlaylistDeprecatedRequest.Builder.class)
 public class AddItemsToPlaylistDeprecatedRequest extends AbstractDataRequest<SnapshotResult> {
 
   /**
-   * @deprecated Use the new endpoints instead.
    * The private {@link AddItemsToPlaylistDeprecatedRequest} constructor.
    *
    * @param builder A {@link AddItemsToPlaylistDeprecatedRequest.Builder}.
@@ -29,7 +29,6 @@ private AddItemsToPlaylistDeprecatedRequest(final Builder builder) {
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Add items to playlist.
    *
    * @return A playlist snapshot ID. The snapshot ID can be used to identify your playlist version in future requests.
@@ -46,13 +45,14 @@ public SnapshotResult execute() throws
   }
 
   /**
-   * @deprecated Use the new endpoints instead.
    * Builder class for building an {@link AddItemsToPlaylistDeprecatedRequest}.
+   *
+   * @deprecated Use {@link AddItemsToPlaylistRequest} instead.
    */
+  @Deprecated
   public static final class Builder extends AbstractDataRequest.Builder<SnapshotResult, Builder> {
 
     /**
-     * @deprecated Use the new endpoints instead.
      * Create a new {@link AddItemsToPlaylistDeprecatedRequest.Builder}.
      * <p>
      * Adding items to the current user's public playlists requires authorization of the {@code playlist-modify-public}
@@ -67,7 +67,6 @@ public Builder(final String accessToken) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The playlist ID setter.
      *
      * @param playlist_id The Spotify ID for the playlist.
@@ -81,7 +80,6 @@ public Builder playlist_id(final String playlist_id) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The item URIs setter.
      * <p>
      * <b>Note:</b> It is likely that passing a large number of item URIs as a query parameter will exceed the maximum
@@ -100,7 +98,6 @@ public Builder uris(final String uris) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The position setter.
      *
      * @param position Optional. The position to insert the items, a zero-based index. If omitted, the
@@ -113,7 +110,6 @@ public Builder position(final Integer position) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The item URIs setter.
      * <p>
      * <b>Note:</b> If the URIs already have been set with {@link #uris(String)}, any URIs listed here will be ignored.
@@ -130,7 +126,6 @@ public Builder uris(final JsonArray uris) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The position setter. You can set it in the request query string or request body, depending on the
      * {@code use_body} parameter.
      *
@@ -151,7 +146,6 @@ public Builder position(final Integer position, final Boolean use_body) {
     }
 
     /**
-     * @deprecated Use the new endpoints instead.
      * The request build method.
      *
      * @return A custom {@link AddItemsToPlaylistDeprecatedRequest}.

diff --git a/...a/se/michaelthelin/spotify/requests/data/playlists/GetPlaylistItemsDeprecatedRequest.java b/...a/se/michaelthelin/spotify/requests/data/playlists/GetPlaylistItemsDeprecatedRequest.java
@@ -12,15 +12,15 @@
 import java.io.IOException;
 
 /**
-  * @deprecated Use the new endpoints instead.
  * Get full details of the tracks or episodes of a playlist owned by a Spotify user.
+ *
+ * @deprecated Use {@link GetPlaylistItemsRequest} instead.
  */
 @Deprecated
 @JsonDeserialize(builder = GetPlaylistItemsDeprecatedRequest.Builder.class)
 public class GetPlaylistItemsDeprecatedRequest extends AbstractDataRequest<Paging<PlaylistTrack>> {
 
   /**
-  * @deprecated Use the new endpoints instead.
    * The private {@link GetPlaylistItemsDeprecatedRequest} constructor.
    *
    * @param builder A {@link GetPlaylistItemsDeprecatedRequest.Builder}.
@@ -30,7 +30,6 @@ private GetPlaylistItemsDeprecatedRequest(final Builder builder) {
   }
 
   /**
-  * @deprecated Use the new endpoints instead.
    * Get a playlist's items.
    *
    * @return A playlist's items.
@@ -45,13 +44,14 @@ public Paging<PlaylistTrack> execute() throws
   }
 
   /**
-  * @deprecated Use the new endpoints instead.
    * Builder class for building a {@link GetPlaylistItemsDeprecatedRequest}.
+   *
+   * @deprecated Use {@link GetPlaylistItemsRequest} instead.
    */
+  @Deprecated
   public static final class Builder extends AbstractDataPagingRequest.Builder<PlaylistTrack, Builder> {
 
     /**
-  * @deprecated Use the new endpoints instead.
      * Create a new {@link GetPlaylistItemsDeprecatedRequest.Builder}.
      * <p>
      * Both Public and Private playlists belonging to any user are retrievable on provision of a valid access token.
@@ -63,7 +63,6 @@ public Builder(final String accessToken) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The playlist ID setter.
      *
      * @param playlist_id The Spotify ID for the playlist.
@@ -77,7 +76,6 @@ public Builder playlist_id(final String playlist_id) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The fields filter setter.
      *
      * @param fields Optional. Filters for the query: a comma-separated list of the fields to return.
@@ -93,7 +91,6 @@ public Builder fields(final String fields) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The limit setter.
      *
      * @param limit Optional. The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 50.
@@ -106,7 +103,6 @@ public Builder limit(final Integer limit) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The offset setter.
      *
      * @param offset Optional. The index of the first item to return. Default: 0 (the first object).
@@ -119,7 +115,6 @@ public Builder offset(final Integer offset) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The market country code setter.
      *
      * @param market Optional. An ISO 3166-1 alpha-2 country code. Provide this
@@ -134,7 +129,6 @@ public Builder market(final CountryCode market) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The additional types setter.
      *
      * @param additionalTypes Optional. A comma-separated list of item types that your client supports
@@ -149,7 +143,6 @@ public Builder additionalTypes(final String additionalTypes) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The request build method.
      *
      * @return A custom {@link GetPlaylistItemsDeprecatedRequest}.

diff --git a/...e/michaelthelin/spotify/requests/data/playlists/RemovePlaylistItemsDeprecatedRequest.java b/...e/michaelthelin/spotify/requests/data/playlists/RemovePlaylistItemsDeprecatedRequest.java
@@ -11,15 +11,15 @@
 import java.io.IOException;
 
 /**
-  * @deprecated Use the new endpoints instead.
  * Remove one or more items from a user’s playlist.
+ *
+ * @deprecated Use {@link RemovePlaylistItemsRequest} instead.
  */
 @Deprecated
 @JsonDeserialize(builder = RemovePlaylistItemsDeprecatedRequest.Builder.class)
 public class RemovePlaylistItemsDeprecatedRequest extends AbstractDataRequest<SnapshotResult> {
 
   /**
-  * @deprecated Use the new endpoints instead.
    * The private {@link RemovePlaylistItemsDeprecatedRequest} constructor.
    *
    * @param builder A {@link RemovePlaylistItemsDeprecatedRequest.Builder}.
@@ -29,7 +29,6 @@ private RemovePlaylistItemsDeprecatedRequest(final Builder builder) {
   }
 
   /**
-  * @deprecated Use the new endpoints instead.
    * Remove items from a playlist.
    *
    * @return A playlist snapshot ID. The snapshot ID can be used to identify your playlist version in future requests.
@@ -46,13 +45,14 @@ public SnapshotResult execute() throws
   }
 
   /**
-  * @deprecated Use the new endpoints instead.
    * Builder class for building a {@link RemovePlaylistItemsDeprecatedRequest}.
+   *
+   * @deprecated Use {@link RemovePlaylistItemsRequest} instead.
    */
+  @Deprecated
   public static final class Builder extends AbstractDataRequest.Builder<SnapshotResult, Builder> {
 
     /**
-  * @deprecated Use the new endpoints instead.
      * Create a new {@link RemovePlaylistItemsDeprecatedRequest.Builder}.
      * <p>
      * Removing items from an user's public playlists requires authorization of the {@code playlist-modify-public}
@@ -67,7 +67,6 @@ public Builder(final String accessToken) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The playlist ID setter.
      *
      * @param playlist_id The Spotify ID for the playlist.
@@ -81,7 +80,6 @@ public Builder playlist_id(final String playlist_id) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The item URIs setter.
      * <p>
      * There are several ways to specify which tracks or episodes to remove, determined by the request parameters.
@@ -105,7 +103,6 @@ public Builder tracks(final JsonArray tracks) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The playlist snapshot ID setter.
      * <p>
      * To guard against errors when concurrent edits happen to the same playlist, we recommend specifying a snapshot ID.
@@ -127,7 +124,6 @@ public Builder snapshotId(final String snapshotId) {
     }
 
     /**
-  * @deprecated Use the new endpoints instead.
      * The request build method.
      *
      * @return A custom {@link RemovePlaylistItemsDeprecatedRequest}.