Pagination

Many of the REST API's make use of a pagination strategy for dealing with operations that can return a large number of items. This strategy is built around the notion of a continuationToken and a page size that determines the maximum number of items that can be returned in a single response.

As of release 3.74.0, pagination offers a default of 50 items for the assets and components APIs; this setting is not configurable.

When a continuationToken is present in a response and has a non-null value, this signifies that there are more items available:

Request

GET /service/rest/v1/<api>?<query>

Response

{
  "items" : [\
    ...\\
  ],
  "continuationToken" : "88491cd1d185dd136f143f20c4e7d50c"
}

The API that produced the response will take a continuationToken as an additional argument to the original query to signify that the next page of results is desired:

Request (next page)

GET /service/rest/v1/<api>?<query>&continuationToken=88491cd1d185dd136f143f20c4e7d50c

If this response also contains a non-null continuationToken, then its value can again be added to the original query to get the next page. This continues until the response returns a continuationToken with a value of null which signifies that there are no more pages of results.

Example Python Script

This example uses Python scripting and the Search API to search the contents of a repository and save the results to a text file. The script continues to make requests to the repository until the continuationToken is null.

import requests
import json

repository_url = 'https://repo.company.com/'
source_repository = 'maven-hosted'
file_name = 'search_results.json'
source_url = repository_url \
   + '/service/rest/v1/search?repository=' \
   + source_repository

nx_token = None
read_again = True
items = []

while read_again == True:
  if not ( nx_token is None):
    url = source_url + "&continuationToken=" + nx_token

response = requests.get(url)
  if response.status_code != 200:
    print('Error: ', response.status_code)
    exit(0)

results = response.json()
  nx_token = results['continuationToken']
  items.extend(results['items'])

if nx_token is None:
    read_again = False

pretty = json.dumps(items, indent=4)
with open(file_name, "w+") as file:
    file.write(pretty)

Search results

No results found