Pagination

What is Pagination?

Pagination is the process of dividing content into discrete pages.

Benefits

It allows for faster response times to requests against large datasets like Customers, Products and Sales Orders, thus providing a more responsive and flexible API for your mission-critical applications.

How does Unleashed’s API use pagination?

The Unleashed API currently does not support pagination on the following endpoints:

All remaining API endpoints that return multiple records will be enhanced to include pagination over time.

Requesting a page

Pages are requested by putting the page number into the URL: https://api.unleashedsoftware.com/{endpoint}/{pagenumber}, where {endpoint} and {pagenumber} are placeholders.

For example, if you wanted to retrieve the 1st page of 200 records from the Customer endpoint we would write https://api.unleashedsoftware.com/Customers/1. Alternatively, because the first page is always the default page number we could shorten this to https://api.unleashedsoftware.com/Customers.

Note: To get the second page you would use https://api.unleashedsoftware.com/Customers/2 and so on. If the 10th page is the final page we would then request it with https://api.unleashedsoftware.com/Customers/10.

Page size

The default page size is 200 records, but is configurable by adding the desired page size in the URL querystring:

https://api.unleashedsoftware.com/{endpoint}/{pagenumber}?pageSize={pagesize}.

The minimum page size is 1 and the maximum page size is 1000 records.

If you want to retrieve the 3rd page of 500 SalesOrders records (ie. 1001st to 1500th record) then you would use this URL:

https://api.unleashedsoftware.com/SalesOrders/3?pageSize=500.

Note: Requesting large numbers of records from an endpoint can be susceptible to poor network performance. If you experience delayed API requests, please try reducing your page size.

Pagination info

In the endpoints that support Pagination a Pagination structure is returned with the multi-record dataset to provide some information regarding how many records there are overall and how many pages of data can be retrieved.

Below is an example of this structure in XML for a Customer’s dataset.

<Customers xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.unleashedsoftware.com/version/1">
	<Pagination>
		<NumberOfItems>675</NumberOfItems>
		<PageSize>100</PageSize>
		<PageNumber>3</PageNumber>
		<NumberOfPages>7</NumberOfPages>
	</Pagination>
	<Customer>
		<Guid>a798eaba-64a5-4a56-8bbe-1585040cd225</Guid>
		<LastModifiedOn>2013-02-11T22:04:30.98</LastModifiedOn>
		...
	</Customer>
</Customers>

API endpoints that do not yet have the Pagination info returned need to page starting at page 1.

If the page was only partially populated then they have reached the last page. However, if the page was fully populated then they should retrieve the next page; and so on.

Pagination example

If you wanted to retrieve and then process all your Sales Orders from Unleashed. Firstly, you would request the first page of Sales Orders data using this URL:

https://api.unleashedsoftware.com/SalesOrders/1?pageSize=1000

In this example we have specified the maximum page size of 1000 records. If you want to retrieve your data in smaller chunks you can use a smaller page size or even stick with the default page size of 200.

Let’s assume that the following data set was returned.

<SalesOrders xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.unleashedsoftware.com/version/1">
	<Pagination>
		<NumberOfItems>3812</NumberOfItems>
		<PageSize>1000</PageSize>
		<PageNumber>1</PageNumber>
		<NumberOfPages>4</NumberOfPages>
	</Pagination>
	<SalesOrder>
		... 1000 SalesOrders
	</SalesOrder>
</SalesOrders>

From the Pagination info we can tell that there will be 3 more pages, two of 1000 records and the last one with 812 records. We can then retrieve the pages 2, 3 and 4 in turn like so:

https://api.unleashedsoftware.com/SalesOrders/2?pageSize=1000 ==> Will result in 1000 records bringing the total so far up to 2000

https://api.unleashedsoftware.com/SalesOrders/3?pageSize=1000 ==> will result in 1000 records bringing the total so far up to 3000

https://api.unleashedsoftware.com/SalesOrders/4?pageSize=1000 ==> will result in 812 records bringing the total so far up to 3812

Because the URLs for the different pages only vary by page number, you can use a simple loop to iterate through them.