Pagination in CalAmp Telematics Cloud

Introduction

Requests to the CalAmp Telematics Cloud platform (CTC) could result in a lot data being returned. In some cases it can be too much data for the client to handle. It can also cause unnecessary load on the server to fetch, collate and transform all that data. Additionally, the client might not even be interested in receiving all that data and especially on mobile devices it can lead to data bandwidth wastage.
To limit the exposure to such unwanted side effects of fetching data, CTC now introduces paginated responses as explained below.

Specifics

1. New request parameters - pg, pgsize, sort
   • pg - Page number, starting at 1.
   • pgsize - How many records to retrieve. Defaults to 10, max 100. Overrides maxResults defined in /search requests.
   • sort - Comma separated list of searchable properties. If not supplied will default to id property. Sort direction can be specified via +/-. No sign == + == Ascending
2. Only top-level collections are paginated. Any collection type properties of a resource are not paginated.
   • GET /accounts/123/devices response, returning a list of devices, can be paginated.
   • account.subAccounts in response to GET /accounts/123 is not paginated.
3. Responses with collections will now include two additional properties - _links and totalCount
   • totalCount - the total number of resources, accessible by the logged in user, that satisfy the request.
   • _links - a collection of Link with well-defined relations that are not direct properties of the resource(s) retrieved. Each member of this collection has an href and a rel property. The following relations will be used for pagination: self, prev, next, first, last as defined by RFC5988.
   • Following rules apply to the _links collection:
     • self is always present. This is analogous to a resource's _self property and represents the request.
     • first is always present.
     • prev is present only if you’re not on the first page.
     • next is present only if you’re not on the last page.
     • last is always present.
     • Order of the elements in the _links collection is not defined.
4. The pagination parameters can be added to any request.
5. The minimum API Version for which pagination will be enforced is v2.1.
6. The API version can be specified either in the Content-Type HTTP header or as a request parameter. The API version is specified as v=NN.NN
7. If a request is made with v=2.1, and no pagination parameters are provided, they will default as follows: pg=1, pgsize=10, sort=id
8. For any API version below 2.1, pagination is not enforced.
9. For API version < 2.1, pagination can still be used by explicitly providing the pagination parameters.
10. If the pagination parameters are specified multiple times in the request, the following rules apply:
    • pg - Only the first value is used.
    • pgsize - Only the first value is used.
    • sort - All occurrences are combined into a single sort in the order they are specified.

Examples

1. Pagination enforced using defaults pg=1, pgsize=10, sort=id due to v=2.1
   GET /accounts/2/devices?v=2.1

2. Pagination not enforced, all devices returned.
   GET /accounts/2/devices

3. Pagination not enforced, all devices returned.
   GET /accounts/2/devices?v=2.0

4. Pagination with pg=2, pgsize=5, sort=id
GET /accounts/2/devices?v=2.1&pg=2&pgsize=5
   For pagination, the above request is equivalent to
   GET /accounts/2/devices?pg=2&pgsize=5

5. Pagination with pg=2, pgsize=5, sorted first by name DESC and then account ASC.
   GET /accounts/2/devices?pg=2&pgsize=5&sort=-name,account

6. Pagination with pg=1, pgsize=5, sorted first by name DESC and then account ASC.
   GET /accounts/2/devices?pgsize=5&sort=-name,account

7. Pagination of /search with pg=1, pgsize=5, sorted first by name DESC and then account ASC.
   POST /devices/search?pg=1&pgsize=5&sort=-name,account

   {"search":{
     "searchTerms":{"name":"Device*", "account":"2,3"},
     "maxResults":25
   }
   

   Note: pgsize overrides maxResults defined in the search object.

8. Multiple pagination parameters specified.
   GET /accounts/123/devices?pg=1&pgsize=5&sort=name&pg=5&sort=-account&pgsize=10
   The above request is equivalent to
   GET /accounts/123/devices?pg=1&pgsize=5&sort=name,-account

9. _links
   GET /accounts/123/devices?pg=3&pgsize=20
   Might return a response like:

   {"response": {
     "results": [ "device":{}, 
                  "device":{},
                  "device":{},
                  ...<20 devices sorted by name>}],
     "count":193,
     "_links": [ 
       {"href":"/accounts/123/devices?pg=3&pgsize=20", "rel":"current"}, 
       {"href":"/accounts/123/devices?pg=1&pgsize=20", "rel":"first"},  
       {"href":"/accounts/123/devices?pg=2&pgsize=20", "rel":"prev"}, 
       {"href":"/accounts/123/devices?pg=4&pgsize=20", "rel":"next"}
       {"href":"/accounts/123/devices?pg=10&pgsize=20", "rel":"last"}]
   }}
   

   GET /accounts/123/devices?pg=10&pgsize=20 will then return a response like:

   {"response": {
     "results": [ "device":{}, 
                  "device":{},
                  "device":{},
                  ...<13 devices sorted by name>}],
     "count":193,
     "_links": [ 
       {"href":"/accounts/123/devices?pg=10&pgsize=20", "rel":"current"}, 
       {"href":"/accounts/123/devices?pg=1&pgsize=20", "rel":"first"},  
       {"href":"/accounts/123/devices?pg=9&pgsize=20", "rel":"prev"},
       {"href":"/accounts/123/devices?pg=10&pgsize=20", "rel":"last"}]
   }}
   

Version 1.1 updated on 04/27/2017.