Pagination in IBM Storage Scale native REST API

The IBM Storage Scale native REST API feature includes pagination support to optimize performance and handle large collections. Listing resource collections, such as filesets, can be an expensive operation when the collection contains many items. Pagination helps improve efficiency by reducing lookup times and controlling the size of responses as collections grow.

The following characteristics apply to IBM Storage Scale native REST API endpoints that implement pagination:

The IBM Storage Scale native REST API endpoints that implement pagination accept the page_size and page_token. Both of these parameters are optional for requests.
- page_size: Specifies the number of items that need to be returned for the request. If not specified, a default value is used, dependent on the collection being listed.
- page_token: Specifies a pointer to the starting item in the collection for the request. If not specified, the default is an empty page token, which means that the output begins with the first item in the collection and returns up to page_size items or the end of the collection if the size of the collection is smaller than page_size.
  Note: The page token is base64-encoded. The contents of the token might change at any time, so decoded contents must not be relied upon.
The IBM Storage Scale native REST API endpoints that implement pagination return a next_page_token field when collections contain items beyond the page returned. If the next_page_token field is empty, the request has reached the end of the collection.

Examples

The following example displays the LIST request with page_size =1 query parameter for two total items in the collection:

curl -X 'GET'   'https://stgbladeh99:8000/scalemgmt/v3/filesystems/fs0/filesets?page_size=1'   -H 'accept: application/json' -k
{
	"filesets":  [
		{
			"name":  "root",
			"id":  0,
			"status":  "FILESETSTATUS_LINKED",
			"path":  "/fs0"
		}
	],
	"next_page_token":  "MQ=="
}

The following example displays the LIST request with

page_size
=

and page_token=MQ== query parameter for two total items in collection:

curl -X 'GET'   'https://example.com:8000/scalemgmt/v3/filesystems/fs0/filesets?page_size=1&page_token=MQ%3D%3D'   -H 'accept: application/json' -k
{
	"filesets":  [
		{
			"name":  "fset1",
			"id":  1,
			"status":  "FILESETSTATUS_UNLINKED",
			"path":  "--"
		}
	]
}

The following examples show the LIST request for no query parameters for two total items in the collection:


curl -X 'GET' \
   'https://example.com:8000/scalemgmt/v3/filesystems/fs0/filesets' \
   -H 'accept: application/json' -k
{
	"filesets":  [
		{
			"name":  "root",
			"id":  0,
			"status":  "FILESETSTATUS_LINKED",
			"path":  "/fs0"
		},
		{
			"name":  "fset1",
			"id":  1,
			"status":  "FILESETSTATUS_UNLINKED",
			"path":  "--"
		}
	]
}

scalectl command

All commands that implement pagination support following flags to control how the command paginates through the collection:

--no-pagination: Returns only one page of results. Does not follow next_page_token.
--page-size int: Specifies the number of items per API request.
--max-items int: Specifies the maximum number of items to list.
--page-token string: Specifies the token to retrieve the next set of items. If the number of items (--max-items) in the output is fewer than the total number of items in the collection, the response includes a next_page_token value, which can be used in a subsequent request.

Examples

To list all items in the collection, issue the following command:

scalectl fileset list fs0

A sample output is as follows:

Fileset name | Id | Status | Path  
==================================
  root         | 0  | link   | /fs0  
  fset1        | 1  | unlink | --

To list at most one item in the collection, issue the following command:

scalectl fileset list fs0 --max-items 1

A sample output is as follows:

Fileset name | Id | Status | Path  
==================================
  root         | 0  | link   | /fs0

To disable the pagination, issue the following command:

scalectl fileset list fs0 --no-pagination --page-size 1

A sample output is as follows:

  Fileset name | Id | Status | Path  
==================================
  root         | 0  | link   | /fs0  

NEXT PAGE TOKEN: MQ==

To follow the page token, issue the following command:

scalectl fileset list fs0 --no-pagination --page-size 1 --page-token MQ==

A sample output is as follows:

Fileset name | Id | Status | Path  
==================================
  fset1        | 1  | unlink | --    

NEXT PAGE TOKEN: <END OF LIST>