Pagination

The Cardinus API supports pagination of records to retrieve a subset of all data in the system. This will help both the API and the client support large datasets without creating huge data responses. Every endpoint for retrieving multiple records supports pagination †. There are two parameters that can be used to control the pagination. The parameters are case insensitive and both optional.

Parameter	Description	Default value if omitted	Maximum value
`PageSize`	The number of records in the page of results	100	1000
`PageNumber`	The index of the page (starting at 1) to return	1	N\A

To use, append one or both of the parameters onto the URL in a standard query string format.

https://online.cardinus.com/api/Assessments?PageNumber=5&PageSize=200

As seen in the example above, calling the get Assessments endpoint, we also pass the PageNumber variable. Here it is set to page 5 and we pass the variable PageSize as well, here it is set to 200 items per page. With this ability you can jump to any page via the URL and reset the items per page via changing the numbers on the URL request.

† Except for the api/reports endpoint.

Wrapped data response

Using the paged response the data will always look like this, showing the actual data items within the wrapped paged information, as per the example below:

{
  "PageNumber": 5,
  "PageSize": 200,
  "FirstPage": "https://online.cardinus.com/api/Assessments?pageNumber=1&pageSize=200",
  "LastPage": "https://online.cardinus.com/api/Assessments?pageNumber=15&pageSize=200",
  "TotalPages": 15,
  "TotalRecords": 2918,
  "NextPage": "https://online.cardinus.com/api/Assessments?pageNumber=6&pageSize=200",
  "PreviousPage": "https://online.cardinus.com/api/Assessments?pageNumber=4&pageSize=200",
  "ItemsCount": 200,
  "Items": [
   {
		.................
   }
  ],
  "Succeeded": true,
  "Errors": null,
  "Message": null
}

Here the paged response is broken down to show the following:

Property	Value
`PageNumber`	The current page of data being displayed
`PageSize`	The amount of data items (in the Items: {}) shown
`FirstPage`	The URL to access the first page
`LastPage`	The URL to access the last page
`TotalPages`	The total pages available to navigate at the current page size.
`TotalRecords`	The total amount of data items
`NextPage`	The URL to move to the next page (null indicates no more pages)
`PreviousPage`	The URL to move to the previous page (null indicates only one page of data)
`ItemsCount`	Shows the count of items on the page being displayed.
`Items`	Enclosed brackets showing the actual data items in an array
`Succeeded`	Either true or false, true indicates successful completion, false an error
`Errors`	null indicates no errors, otherwise count shows error items
`Message`	null indicates no message, otherwise message displayed possibly an error

Using the above information, allows navigation between pages just by utilising the attributes NextPage and PreviousPage URLs in the response JSON. When there are no more pages the NextPage value will be null.

The Pagination page size limit has a maximum number of items per page regardless, this is set to 1000. The default if the PageSize is not set on the URL, is 100 which the user can change with the maximum limit of 1000, anything above that will be ignored. If you enter a page number higher than the number of available pages then the response will contain zero items.

C# snippet

while(nextPage != null)
{
	await httpClient.GetAsync(nextPage).ContinueWith(async(itemTask) =>
    {
        var response = await itemTask;
        if (response.IsSuccessStatusCode)
        {
            string jsonString = await response.Content.ReadAsStringAsync();
            var result = JsonConvert.DeserializeObject<YOURWRAPPERCLASS>(jsonString);
            if (result != null)
            {
                // Check for items
                if (result.items.Any())
			    {
				    // PROCESS YOUR DATA HERE
			    }                                                           
                // Get the URL for the next page
                nextPage = result.nextPage;
            }
		}
		else
        {
            // End loop if we get an error response.
            nextPage = null;
        }                 
    });                

}

The above is a basic traversal code snippet to get all items in the paged response wrapper until no more pages are available. This is Pseudocode to give an idea of how to use the JSON data response in your code.

Table of Contents

Pagination

Wrapped data response

C# snippet