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 up to 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 four 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.