Pagination

API requests that return more than one item may be paginated, which simply means the total number of items is split into logical pages, in the same way that a book is split into pages. Each page will have a certain number of items in it from one upto the page limit - empty datasets are never paginated.

When pagination is enabled the following query string parameters are supported:

ParameterDescription
pageThe current page of the pagination dataset to view. The page number is 1-based, so omitting or specifying a non-positive number will return the first page.
page_sizeThe page size to divide the dataset into. The default amount (if not specified) is 30 items per page and the maximum configurable is 500 items per page.

When pagination occurs, the following headers will be represent in API responses:

HeaderDescription
Link (based on RFC5988Hypermedia links for the previous page (if any) and for the next page (if any). Some of which may require expansion as URI templates.
X-Pagination-CountThe total number of items in the dataset.
X-Pagination-PageThe number of the current page.
X-Pagination-PageTotalThe total number of pages in the dataset.
X-Pagination-PageSizeThe size of each page in the dataset.

The Link header can contain the following rel values:

NameDescription
firstThe link relation to the first page of results. This will only be present if there is more than one page.
prevThe link relation to the previous page of results. This will only be present if the client has requested a page greater than 1.
nextThe link relation to the next page of results. This will only be present if the client has requested a page less than the last/final page.
lastThe link relation to the last/final page of results. This will only be present if there is more than one page.

Let's see it in action:

curl -i -H "X-Api-Key: <key>" 'https://api.cloudsmith.io/package/example/repo/packages/?page=2&page_size=1'

HTTP/1.0 200 OK
Allow: GET, OPTIONS
Content-Type: application/json
Link: <https://api.cloudsmith.io/package/example/repo/packages/?page=1>; rel="first", <https://api.cloudsmith.io/package/example/repo/packages/?page=1>; rel="prev", <https://api.cloudsmith.io/package/example/repo/packages/?page=3>; rel="next", <https://api.cloudsmith.io/package/example/repo/packages/?page=3>; rel="last"
X-Pagination-Count: 3
X-Pagination-Page: 2
X-Pagination-PageTotal: 3
X-Pagination-PageSize: 1
Server: Cloudsmith MCP
Date: Sun, 29 Jan 2017 18:40:55 GMT

[snip]

📘

Page Sizes / Remainders

If the page size is 100 and the dataset size is 400, then there will be 4 pages available for retrieval. If the dataset isn't cleanly divided by the page size the remainder will be on the final page. For example, if the page size is 100 and the dataset size is 350 then the last (4th) page will have 50 items on it.

Cloudsmith is the new standard in Package / Artifact Management and Software Distribution

With support for all major package formats, you can trust us to manage your software supply chain.


Start My Free Trial Now
Cookie Declaration (Manage Cookies)