Skip to content

Watchlist endpoints require pagination #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
UweTrottmann merged 2 commits into from
Mar 6, 2026
Merged

Watchlist endpoints require pagination #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63e2dec
Sync/Users: require pagination for watchlist endpoints
UweTrottmann Mar 6, 2026
1603e03
UsersTest: use default page and limit for list items tests
UweTrottmann Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Next release

* Watchlist endpoints require pagination: deprecate the variants that don't accept page and limit parameters.
* Add warnings to `watchedAt()` setters, update existing warnings
that [Trakt already only stores and returns minute-precision timestamps](https://github.com/trakt/trakt-api/discussions/694).

Expand Down
36 changes: 24 additions & 12 deletions src/main/java/com/uwetrottmann/trakt5/services/Sync.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,16 +431,17 @@ Call<SyncResponse> deleteRatings(


/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistMovies(UserSlug, Extended)}.
* @deprecated Use {@link #watchlistMovies(Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("sync/watchlist/movies")
Call<List<BaseMovie>> watchlistMovies(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistMovies(UserSlug, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/movies")
Expand All @@ -451,6 +452,8 @@ Call<List<BaseMovie>> watchlistMovies(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistMovies(UserSlug, String, String, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/movies/{sort_by}/{sort_how}")
Expand All @@ -463,16 +466,17 @@ Call<List<BaseMovie>> watchlistMovies(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistShows(UserSlug, Extended)}.
* @deprecated Use {@link #watchlistShows(Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("sync/watchlist/shows")
Call<List<BaseShow>> watchlistShows(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistShows(UserSlug, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/shows")
Expand All @@ -483,6 +487,8 @@ Call<List<BaseShow>> watchlistShows(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistShows(UserSlug, String, String, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/shows/{sort_by}/{sort_how}")
Expand All @@ -495,16 +501,17 @@ Call<List<BaseShow>> watchlistShows(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistSeasons(UserSlug, Extended)}.
* @deprecated Use {@link #watchlistSeasons(Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("sync/watchlist/seasons")
Call<List<WatchlistedSeason>> watchlistSeasons(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistSeasons(UserSlug, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/seasons")
Expand All @@ -515,6 +522,8 @@ Call<List<WatchlistedSeason>> watchlistSeasons(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistSeasons(UserSlug, String, String, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/seasons/{sort_by}/{sort_how}")
Expand All @@ -527,16 +536,17 @@ Call<List<WatchlistedSeason>> watchlistSeasons(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistEpisodes(UserSlug, Extended)}.
* @deprecated Use {@link #watchlistEpisodes(Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("sync/watchlist/episodes")
Call<List<WatchlistedEpisode>> watchlistEpisodes(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistEpisodes(UserSlug, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/episodes")
Expand All @@ -547,6 +557,8 @@ Call<List<WatchlistedEpisode>> watchlistEpisodes(
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} required</b>
* <p>
* Like {@link Users#watchlistEpisodes(UserSlug, String, String, Integer, Integer, Extended)}.
*/
@GET("sync/watchlist/episodes/{sort_by}/{sort_how}")
Expand Down
92 changes: 48 additions & 44 deletions src/main/java/com/uwetrottmann/trakt5/services/Users.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -545,10 +545,20 @@ Call<List<RatedEpisode>> ratingsEpisodes(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* @deprecated Use {@link #watchlistMovies(UserSlug, Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("users/{username}/watchlist/movies")
Call<List<BaseMovie>> watchlistMovies(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} optional</b>
* <p>
* Returns all items in a user's watchlist filtered by movies.
* Returns a page of items in a user's watchlist filtered by movies.
* <p>
* The watchlist should not be used as a list of what the user is actively watching. Use a combination of the
* /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
Expand All @@ -561,15 +571,6 @@ Call<List<RatedEpisode>> ratingsEpisodes(
* @see #watchlistMovies(UserSlug, String, String, Integer, Integer, Extended)
*/
@GET("users/{username}/watchlist/movies")
Call<List<BaseMovie>> watchlistMovies(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* Like {@link #watchlistMovies(UserSlug, Extended)}, but you can specify pagination parameters.
*/
@GET("users/{username}/watchlist/movies")
Call<List<BaseMovie>> watchlistMovies(
@Nonnull @Path("username") UserSlug userSlug,
@Query("page") Integer page,
Expand All @@ -578,7 +579,7 @@ Call<List<BaseMovie>> watchlistMovies(
);

/**
* Like {@link #watchlistMovies(UserSlug, Extended)}, but you can specify pagination parameters and a sort order.
* Like {@link #watchlistMovies(UserSlug, Integer, Integer, Extended)}, but you can specify a sort order.
* <p>
* The specified order will be sent in the X-Applied-Sort-By and X-Applied-Sort-How headers.
* <p>
Expand All @@ -600,10 +601,20 @@ Call<List<BaseMovie>> watchlistMovies(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* @deprecated Use {@link #watchlistShows(UserSlug, Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("users/{username}/watchlist/shows")
Call<List<BaseShow>> watchlistShows(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} optional</b>
* <p>
* Returns all items in a user's watchlist filtered by shows.
* Returns a page of items in a user's watchlist filtered by shows.
* <p>
* The watchlist should not be used as a list of what the user is actively watching. Use a combination of the
* /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
Expand All @@ -616,15 +627,6 @@ Call<List<BaseMovie>> watchlistMovies(
* @see #watchlistShows(UserSlug, String, String, Integer, Integer, Extended)
*/
@GET("users/{username}/watchlist/shows")
Call<List<BaseShow>> watchlistShows(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* Like {@link #watchlistShows(UserSlug, Extended)}, but you can specify pagination parameters.
*/
@GET("users/{username}/watchlist/shows")
Call<List<BaseShow>> watchlistShows(
@Nonnull @Path("username") UserSlug userSlug,
@Query("page") Integer page,
Expand All @@ -633,7 +635,7 @@ Call<List<BaseShow>> watchlistShows(
);

/**
* Like {@link #watchlistShows(UserSlug, Extended)}, but you can specify pagination parameters and a sort order.
* Like {@link #watchlistShows(UserSlug, Integer, Integer, Extended)}, but you can specify a sort order.
* <p>
* The specified order will be sent in the X-Applied-Sort-By and X-Applied-Sort-How headers.
* <p>
Expand All @@ -655,10 +657,20 @@ Call<List<BaseShow>> watchlistShows(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* @deprecated Use {@link #watchlistSeasons(UserSlug, Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("users/{username}/watchlist/seasons")
Call<List<WatchlistedSeason>> watchlistSeasons(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} optional</b>
* <p>
* Returns all items in a user's watchlist filtered by seasons.
* Returns a page of items in a user's watchlist filtered by seasons.
* <p>
* The watchlist should not be used as a list of what the user is actively watching. Use a combination of the
* /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
Expand All @@ -671,15 +683,6 @@ Call<List<BaseShow>> watchlistShows(
* @see #watchlistSeasons(UserSlug, String, String, Integer, Integer, Extended)
*/
@GET("users/{username}/watchlist/seasons")
Call<List<WatchlistedSeason>> watchlistSeasons(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* Like {@link #watchlistSeasons(UserSlug, Extended)}, but you can specify pagination parameters.
*/
@GET("users/{username}/watchlist/seasons")
Call<List<WatchlistedSeason>> watchlistSeasons(
@Nonnull @Path("username") UserSlug userSlug,
@Query("page") Integer page,
Expand All @@ -688,7 +691,7 @@ Call<List<WatchlistedSeason>> watchlistSeasons(
);

/**
* Like {@link #watchlistSeasons(UserSlug, Extended)}, but you can specify pagination parameters and a sort order.
* Like {@link #watchlistSeasons(UserSlug, Integer, Integer, Extended)}, but you can specify a sort order.
* <p>
* The specified order will be sent in the X-Applied-Sort-By and X-Applied-Sort-How headers.
* <p>
Expand All @@ -710,10 +713,20 @@ Call<List<WatchlistedSeason>> watchlistSeasons(
@Query(value = "extended", encoded = true) Extended extended
);

/**
* @deprecated Use {@link #watchlistEpisodes(UserSlug, Integer, Integer, Extended)} instead.
*/
@Deprecated
@GET("users/{username}/watchlist/episodes")
Call<List<WatchlistedEpisode>> watchlistEpisodes(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* <b>OAuth {@link TraktV2#accessToken(String) access token} optional</b>
* <p>
* Returns all items in a user's watchlist filtered by episodes.
* Returns a page of items in a user's watchlist filtered by episodes.
* <p>
* The watchlist should not be used as a list of what the user is actively watching. Use a combination of the
* /sync/watched and /shows/:id/progress methods to get what the user is actively watching.
Expand All @@ -726,15 +739,6 @@ Call<List<WatchlistedSeason>> watchlistSeasons(
* @see #watchlistEpisodes(UserSlug, String, String, Integer, Integer, Extended)
*/
@GET("users/{username}/watchlist/episodes")
Call<List<WatchlistedEpisode>> watchlistEpisodes(
@Nonnull @Path("username") UserSlug userSlug,
@Query(value = "extended", encoded = true) Extended extended
);

/**
* Like {@link #watchlistEpisodes(UserSlug, Extended)}, but you can specify pagination parameters.
*/
@GET("users/{username}/watchlist/episodes")
Call<List<WatchlistedEpisode>> watchlistEpisodes(
@Nonnull @Path("username") UserSlug userSlug,
@Query("page") Integer page,
Expand All @@ -743,7 +747,7 @@ Call<List<WatchlistedEpisode>> watchlistEpisodes(
);

/**
* Like {@link #watchlistEpisodes(UserSlug, Extended)}, but you can specify pagination parameters and a sort order.
* Like {@link #watchlistEpisodes(UserSlug, Integer, Integer, Extended)}, but you can specify a sort order.
* <p>
* The specified order will be sent in the X-Applied-Sort-By and X-Applied-Sort-How headers.
* <p>
Expand Down
14 changes: 14 additions & 0 deletions src/test/java/com/uwetrottmann/trakt5/BaseTestCase.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,13 @@ public class BaseTestCase {

private static final boolean DEBUG = true;

protected static final int PAGE_ONE = 1;
protected static final Integer DEFAULT_PAGE_SIZE = 10;
/**
* 1000 is the maximum limit according to the
* <a href="https://github.com/trakt/trakt-api/discussions/681">Upcoming API Changes: Pagination & Sorting Updates discussion</a>.
*/
protected static final int LIST_AND_COLLECTION_MAX_LIMIT = 1000;

private static TraktV2 trakt;
private static TraktV2 traktNoAuth;
Expand Down Expand Up @@ -348,6 +354,14 @@ public static void assertPaginationHeaders(Response<?> response, int expectedPag
assertThat(response.headers().get("X-Pagination-Limit")).isEqualTo(String.valueOf(expectedLimit));
}

/**
* Like {@link #assertPaginationHeaders(Response, int, int)}, but uses {@link #PAGE_ONE} and
* {@link #LIST_AND_COLLECTION_MAX_LIMIT}.
*/
public static void assertListPaginationHeaders(Response<?> response) {
assertPaginationHeaders(response, PAGE_ONE, LIST_AND_COLLECTION_MAX_LIMIT);
}

public static void assertSortOrderHeaders(Response<?> response, String expectedSortBy, String expectedSortHow) {
assertThat(response.headers().get("x-applied-sort-by")).isEqualTo(expectedSortBy);
assertThat(response.headers().get("x-applied-sort-how")).isEqualTo(expectedSortHow);
Expand Down
Loading