Пагинация запросов Web API

Some methods return a set of objects (conversations, users, events etc.). A convenient method of getting all data sets in several consequent request is provided with the help of cursor-based pagination.

Depending on the request, pagination key can be:

1. Object primary key
2. Datetime field (as timestamp)
3. Both datetime and primary key

Pagination in version 2 and higher (current)

This pagination is used if you request API version 2 and above.
Read more about versions.

Pagination v2 query parameters (GET parameters):

• paginate_position - JSON-array. Contains current pagination position. Array elements can differ in different requests. The most common are

  • Primary key pagination. In this case array contains the only element - object's id. Id can be set as integer or string (see id_as_string).
  • Datetime pagination. First array element contains timestamp, the second one - object's id. Object's id is required in order to paginate correctly situation when many objects have same datetime.

  Note: Some requests can not use all paginate directions.

• paginate_count - Integer from 1 to 50. Number of objects to fetch. If paginate_position=around, then paginate_position / 2 objects will be fetched before and after paginate_position. Defaults to 20.

• paginate_direction - [after, before, around]. Paginate direction relative to paginate_position:

  • after means returning objects with position greater than paginate_position.
  • before means returning objects with position less than paginate_position.
  • around will try to fetch objects around paginate_position.

• paginate_including - [true | false]. Whether paginate_position element should be included or not. Defaults to false.

• paginate_page_order - [asc, desc]. Result pagination page order. Defaults to desc.

Pagination v2 response

Paginated response will contain a combination of 2 fields inside meta section:

• next_before_position - when paginate_direction is before or around marks next paginate_position with paginate_direction=before
• next_after_position - when paginate_direction is after or around marks next paginate_position with paginate_direction=after

If a field contains null, then there are no more pages to fetch.

Example:

GET https://api.dashly.app/apps/{ID}/conversations
By default paginate_position=before is used.

{
  "meta": {
    "next_before_position": [
      1684739969.358085,
      1160406004324630614
    ],
    "status": 200
  },
  "data": [
    ... // Objects here
  ]
}

Next requests will look like this:
GET https://api.dashly.app/apps/{ID}/conversations?paginate_position=[1684739969.358085, 1160406004324630614]

Pagination v1 (deprecated)

Used if you use API with major version 1.
Read more about versions.

Note In order to keep system back compatible, parameters contain after, while working as paginate_position=before of v2 pagination.

Important! Pagination v1 has logical error in datetime pagination in case of which some objects may be missed, if they have equal timestamp in pagination key. It's a rare case, but it can occur.

Pagination v1 query parameters (GET parameters):

• after - Contains current pagination cursor. Can keep integer (mostly, primary key), float (timestamp) or string (see id_as_string).
• count - maximum objects to fetch (from 1 to 50). Defaults to: 20.
• including - [true | false]. Whether to include element in after or not.
• page_order - [asc, desc]. Result pagination page order. Defaults to desc.

Pagination v1 response

Response will contain next_after field in meta section:

• next cursor position, if it exists
• null, if there is not next page

Example:

GET https://api.dashly.app/apps/{ID}/conversations

{
  "meta": {
    "next_after": 1684740107.380634,
    "status": 200
  },
  "data": [
    ... // Objects here
  ]
}

Next query will look like:
GET https://api.dashly.app/apps/{ID}/conversations?after=1684740107.380634