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 items to 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 wherelastistrueis received - Incrementing the
pagenumber until it reaches the amount of thetotalPagesresponse 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