,

API Series: Sorting and Paging

Last we left the API series, we were talking about expands and filters and the flexibility they provide when querying data. So today we’re going to discuss paging and sorting, which is extremely important for limiting the amount of data you need at any given time, and how it should be sorted when it gets back to you.

Sorting

When retrieving a list of items, the Znode API supports using the sort parameter to sort the results. The sort parameter is a key-value pair separated by the tilde (~) character, which is configurable. There are only two acceptable values, asc for ascending order and desc for descending order:

key~asc
key~desc

For example, to retrieve all products sorted by name in ascending order, you would use the following endpoint:

GET /products?sort=name~asc

And of course you can combine sorting with expands and filters. For example, to get a list of products and their SKUs, where product name contains “pea”, sorted by wholesale price in descending order, you would make the following API call:

GET /products?expand=skus&filter=name~cn~pea&sort=wholesaleprice~desc

Paging

In many cases, retrieving lists of items needs to be done a page at a time, which the Znode API handles by providing the page parameter. For example, to retrieve page 4 of a list of products with a page size of 25, you will will use the following endpoint:

GET /products?page=index~3,size~25

The page parameter consists of two key-value pairs: index and size. Both key-value pairs are separated by the tilde (~) character and should always be used together, separated by a comma.

NOTE: The index key-value is 0-based.

For endpoints in the Znode API that support paging, the following properties will be returned in the response:

Property Description
PageIndex The current page index that was requested.
PageSize The current page size that was requested.
TotalPages The total number of pages for the request.
TotalResults The total number of results for the request.

And here is an example of what these properties look like as part of the JSON response:

{
    "PageIndex": 3,
    "PageSize": 25,
    "TotalPages": 5,
    "TotalResults": 108,
}