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
  2. Only top-level collections are paginated. Any collection type properties of a resource are not paginated.
  3. Responses with collections will now include two additional properties - _links and totalCount
  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:

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.