Sorting Items in a Response
When you make a basic GET call to one of TrackTik's API endpoints, it will in general return a list of records sorted by their main index (id) numbers. This means that the oldest information is returned first.
That might not be useful in all situations especially when a person is looking for the new data, or needs to sort by name alphabetically, and so on.
To sort the items of a response to an API call, you need to use the "sort" parameter. It sorts in ASCENDING order by default, and you can prefix the value to the parameter with a "-" to reverse it to DESCENDING.
E.g.
Say you want to see the latest list of new employees. You would have a DESCENDING sort on the id index values as they would occur in the database, so you would:
[GET] /rest/v1/employees?sort=-id
Notice the "-" before the "id" to switch the ASC sort order to DESC.
You can also do this on employee names for examples. So for a list of employees by alphabetical names, you would request:
[GET] /rest/v1/employees?sort=name
The sorting feature does not currently support multiple dimensions.
Default Number of Items Returned
By default, if no requested number of result items is defined with a filter parameter, 100 records of the called data entity/endpoint will be returned.
Maximum Number of Returned Items
The maximum number of returned items in a single response is 1000, and you can request up to that limit using the limit parameter.
E.g. You want to request 100 items in the response.
[GET] /zone-clients?limit=1000
"meta": {
"count": 3357,
"request": [
"zone-clients"
],
==> "itemCount": 1000,
"security": {
"granted": true,
"requested": "admin:zone-clients:view",
"grantedBy": "admin:*",
"scope": null
},
"debug": null,
"resource": "zone-clients",
"limit": 1000,
"offset": 0
}
Notice how there are 3357 possible items to return (count value), but that with the limit=1000, and looking at the itemCount value, only 1000 of the 3357 are returned.
Paginating Items Returned (offset)
If you want to see a different subset of the possible items that can be returned, you can use the offset filter to request “the next set of items with a count of <limit>, after the last item of the data set without an offset with a count of <limit>."
E.g.
Let’s say you’re looking at a sorted list of employees in groups of 5 (for performance, or some tool with a GUI). You would request the first 5 with:
[GET] /employees?limit=5&fields=id,name,email&sort=id
{
"id": 1000,
"name": "TrackTIk Support (HQ)",
"email": "E@E.com"
},
{
"id": 1001,
"name": "TrackTik Support (NE)",
"email": ""
},
{
"id": 1002,
"name": "TrackTik Support (NW)",
"email": ""
},
{
"id": 1003,
"name": "TrackTik Support (SE)",
"email": ""
},
{
"id": 1004,
"name": "TrackTik Support (SW)",
"email": ""
}
Now let’s add an offset to get the next 5, not including the previous items already returned:
{
"id": 1005,
"name": "Joan Slater",
"email": ""
},
{
"id": 1006,
"name": "John Mills",
"email": "BMills@prioritysecurity.com"
},
{
"id": 1007,
"name": "Jake Bond",
"email": "JBond@prioritysecurity.com"
},
{
"id": 1008,
"name": "Molly Sutherland",
"email": "MSutherland@prioritysecurity.com"
},
{
"id": 1009,
"name": "Mike Brown",
"email": "mbrown@prioritysecurity.com"
}
Summary
You already know about limits:
[GET] /employees?limit=5&fields=id,name,email&sort=id
A request like that will get the first 5 records stored in the database (because of the primary key sorting of sort=id parameter).
But to get the next 5 after that, you can use an offset value. The offset value is the number of rows to skip over before beginning the count up to the limit. So if the previous call returned the first 5, to get the next 5 after that would be:
[GET] /employees?limit=5&fields=id,name,email&sort=id&offset=5
And for the next 5 after the first 10:
[GET] /employees?limit=5&fields=id,name,email&sort=id&offset=10
When developing a call loop to essentially paginate like this, you would set the limit variable to 5, and the offset to the limit variable times the number of pages to skip ahead to.
First (no pages) 5: limit 5, offset 0 (offset = 5 x 0)
Second 5 (page 1): limit 5, offset 5 (offset = 5 x 1)
Third 5 (page 2): limit 5, offset 15 (offset = 5 x 2)