Skip to content

Pagination

Introduction

All resources that return lists of elements can be paged e.g.:

searchMeta field is appended after the returned array of elements in the JSON response:

{
  "triggers": [
      // Array of Trigger objects
  ],
  "searchMeta": {
    "filter": "",
    "startIndex": 0,
    "maxResult": 50,
    "prevResults": "",
    "count": null,
    "orderBy": "created",
    "nextResults": "",
    "queryType": "NORMAL",
    "order": "ASC"
  }
}

You can add paging parameters to any GET that supports paging.

Parameter Type Description Default
startIndex Integer Offset of first record (0 based) 0
maxResult Integer Number of records to return 50
prevResults1 String URL of previous result set, or an empty string
nextResults1 String URL of next result set, or an empty string
orderBy2 String Field name used for sorting created
order String ASCending, DESCending ASC

1nextResults and previousResults contain the URL with parameters to return the next or previous page of results. These are not parameters that can be set on the GET they are only returned in the JSON output.

If nextResults contains an empty string, then the end of the record set has been reached.

2By default, results will be ordered by created - the creation timestamp for the record. Each resource has different sortable fields that can be used to specify the order.

Using pagination parameters

Let's assume we have 8 devices assigned to our account. We want to return them in groups of three.

1. Request the first page with maximum 3 devices:

GET /device?maxResult=3

Returns a searchMeta:

{
  "devices": [
    {
      // Object representing Device 1
    },
    {
      // Object representing Device 2
    },
    {
      // Object representing Device 3
    }
  ],
  "searchMeta": {
    "filter": "",
    "startIndex": 3,
    "maxResult": 3,
    "prevResults": "",
    "count": null,
    "orderBy": "created",
    "nextResults": "https://api.kontakt.io/device?startIndex=3&maxResult=3",
    "queryType": "NORMAL",
    "order": "ASC"
  }
}

2. Request the next page.

This will return devices 4-6 unless the result set is exhausted.

GET /device?startIndex=3&maxResult=3

Returns a searchMeta:

{
  "devices": [
    {
      // Object representing Device 4
    },
    {
      // Object representing Device 5
    },
    {
      // Object representing Device 6
    }
  ],
  "searchMeta": {
    "filter": "",
    "startIndex": 3,
    "maxResult": 3,
    "prevResults": "https://api.kontakt.io/device?startIndex=0&maxResult=3",
    "count": null,
    "orderBy": "created",
    "nextResults": "https://api.kontakt.io/device?startIndex=6&maxResult=3",
    "queryType": "NORMAL",
    "order": "ASC"
  }
}

3. Retrieve the final page.

GET /device?startIndex=6&maxResult=3

Returns a searchMeta:

{
  "devices": [
    {
      // Object representing Device 7
    },
    {
      // Object representing Device 8
    }
  ],
  "searchMeta": {
    "filter": "",
    "startIndex": 6,
    "maxResult": 3,
    "prevResults": "https://api.kontakt.io/device?startIndex=3&maxResult=3",
    "count": null,
    "orderBy": "created",
    "nextResults": "https://api.kontakt.io/device?startIndex=3&maxResult=2",
    "queryType": "NORMAL",
    "order": "ASC"
  }
}

The empty value for nextResults indicates that there are no further elements to be returned.