Risk Cloud API: Pagination

Updated on: January 17, 2023

The Risk Cloud API contains a variety of endpoints that may return a substantial amount of listed data. These endpoints utilize a style of offset pagination to provide a means of processing the data in smaller portions.

Page Requests

Risk Cloud API endpoints that support Pagination accept two optional query parameters to indicate what portion of data to return.

  • page - an integer representing the zero-indexed page number (must not be lessthan 0, defaults to 0)
  • size - an integer representing the size of the page and maximum number of itemsto be returned (must not be less than 1, defaults to 20)

These query parameters function conceptually similar to how pages are implemented in the Risk Cloud UI, where the page is the page number value, albeit zero-indexed, and size is the Results per page value.

Example

The Field Read All endpoint of GET /api/v1/fields utilizes Pagination. If there are 50 active Fields (numbered 1-50) in a Risk Cloud environment, then the following query parameters will return the following Fields.

Page Size Request Fields
None (Default 0) None (Default 20) GET /api/v1/fields 1-20
0 20 GET /api/v1/fields?page=0&size=20 1-20
1 20 GET /api/v1/fields?page=1&size=20 21-40
2 20 GET /api/v1/fields?page=2&size=20 41-50
0 8 GET /api/v1/fields?page=0&size=8 1-8
1 8 GET /api/v1/fields?page=1&size=8 9-16

Page Responses

When a Risk Cloud API endpoint returns a Page, the response body contains a variety of properties. 

Property Type Description
content array A list of the returned items
number integer The zero-indexed page number
size integer The size of the page and maximum number of items to be returned
totalElements integer The total number of items available
totalPages integer The total number of pages available based on the size
first boolean Whether the current page is the first one
last boolean Whether the current page is the last one
empty boolean Whether the current page is empty
numberOfElements integer The number of items currently on this page
sort object The sorting parameters for the page
sort.empty boolean Whether the current page is empty
sort.sorted boolean Whether the page items are sorted
sort.unsorted boolean Whether the page items are not sorted

Page Processing

Depending on the integration, there are multiple strategies for processing data from a Risk Cloud API endpoint that supports Pagination.

  • Bulk
  • Iteration

Bulk

The Bulk strategy involves sending a single request to obtain a bulk result. This is accomplished by providing a large value for the size query parameter. The size value should be large enough to surpass the expected maximum amount of possible returned items. An example would be: GET /api/v1/fields?size=1000

The items can then be obtained from the content property of the response.

Pseudocode Example

CALL GetFields with size as 1000 RETURNING response 
SET items to response.content

Iteration

The Iteration strategy involves sending multiple requests and assembling a result. This can be accomplished in multiple ways, including the following.

  • Incrementing the pagenumber until a response where last is true is received
  • Incrementing the page number until it reaches the amount of the totalPagesresponse property

Pseudocode Example

SET items to [] 
SET index to 0 
REPEAT 
  CALL GetFields with page as index RETURNING response 
  APPEND response.content to items 
  INCREMENT index 
UNTIL response.last = true