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:

Parameter

Description

page

The 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_size

The 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:

Header

Description

Link (based on RFC5988

Hypermedia 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-Count

The total number of items in the dataset.

X-Pagination-Page

The number of the current page.

X-Pagination-PageTotal

The total number of pages in the dataset.

X-Pagination-PageSize

The size of each page in the dataset.

The Link header can contain the following rel values:

Name

Description

first

The link relation to the first page of results. This will only be present if there is more than one page.

prev

The link relation to the previous page of results. This will only be present if the client has requested a page greater than 1.

next

The 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.

last

The 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)