docs(api): document the limit constraints on paginated endpoints

[jeherve]

Fixes #924.

The pagination guide tells readers that every paginated method defaults to 10 items per page, and the reference pages generated from this repo mention no default and no maximum at all, because pageQuerySchema describes limit as just "The number of items per page".

Neither matches the API. Sending no limit and reading X-Pagination-Limit back:

Endpoint	X-Pagination-Limit
/users/{id}/history	100
/movies/trending, /movies/popular, /movies/anticipated	100
/shows/trending, /shows/popular	100
/users/{id}/watchlist, /users/{id}/lists	100
/movies/{id}/lists, /shows/{id}/lists	100
/search/{type}	50
/movies/{id}/comments, /shows/{id}/comments	10

The maximum has been 250 since June 15, and a larger value is clamped to it rather than rejected:

requested limit	X-Pagination-Limit	items returned
250	250	250
500	250	250
1000	250	250

I hit this in a plugin of mine. It asked for the page count without a limit, got a count back for 100-item pages, then walked those pages at limit=10, and imported a tenth of my history.

pageQuerySchema is shared by endpoints whose defaults disagree, so this does not name a default. It says that the default varies, that sending an explicit value is the safe thing to do, and where the ceiling is.

What this deliberately leaves alone

• The prose guide on docs.trakt.tv, which does not appear to live in this repo.
• recommendationsQuerySchema, which has its own separate limit.
• limitlessQuerySchema, where limit can also be the value all.
• Validation behaviour. This is a description change only, so nothing that used to be accepted is now rejected. I left .max(250) off on purpose, since ‼️ Upcoming API Changes: Watched Endpoints Pagination & Extended Defaults #775 notes the effective page size can be lower for heavier extended modes, and a hard schema constraint would claim more than I can verify.

Pull Request Checklist

• Clear and Concise Title
• Detailed Description
• Tests: description-only change, no behaviour to test. The generated spec was checked by hand for the new text.
• Coding Standards
• Commit Messages: Conventional Commits, docs(api)
• Documentation: this is the documentation change
• Code Review

[kevincador]

Thanks for opening this! The pagination wording definitely needed some clarification.

I’ve proposed slightly different wording, mostly to avoid presenting 10 and 250 as fixed rules since those values can vary depending on the endpoint.

I also went ahead and updated the online pagination docs. They were indeed outdated and a bit misleading about the defaults and limits, so thanks for bringing attention to this.

[kevincador]

I’d avoid making 250 sound like a fixed maximum, since both the default and maximum can vary by endpoint.

Maybe something like:

The number of items per page. Defaults and maximums vary by endpoint. When pagination parameters are omitted, a low default limit is applied (often 10). When a limit is provided, it is capped at the endpoint maximum (often 250); higher values are clamped rather than rejected.