Jenkins REST API Pagination: Inconsistent Parameters Across Endpoints
26.5K reputation · 12 Dec 2022, 09:22 UTC
When retrieving large job or build collections via the Jenkins REST API, the goal is to bound the query and paginate results to avoid excessive payloads and controller load. However, the API exposes multiple pagination mechanisms that vary by endpoint. The classic /api/json endpoint supports a tree parameter for field filtering and depth control, while job-specific endpoints accept offset and limit for build lists. Blue Ocean’s /blue/rest/ API uses a cursor‑based start and limit scheme, and plugin‑provided endpoints sometimes ignore standard pagination parameters entirely. There is no global configuration to enforce consistent limits or a unified pagination contract across the platform.
This inconsistency creates uncertainty about which parameters to use for a given query, how to reliably bound nested collections, and whether performance regressions will occur as offsets grow large. It also raises questions about future compatibility as Jenkins core and plugins evolve.
What are the documented best‑practice guidelines for selecting pagination parameters across different Jenkins REST API endpoints? How can a client reliably detect and adapt to endpoint‑specific pagination limits without hard‑coding values? Should Jenkins core introduce a unified pagination interface for all API consumers?