# Getting Started

Many of Tillhub's resources exposed by the API, support pagination. Pagination allows getting resources from the API in an iterative manner (page by page). The tillhub built-in pagination mechanism is a generic one, allowing the same pagination settings over all the iterable resources.

# Pagination in the API

# Iterable resources request settings

As an example, let's look at the products resource. Products are an iterable resource, hence the request to get products can include pagination settings as well. The following cUrl can serve as an initial call to get products (and hence to receive the first page). Notice the limit query parameter set to 100:

curl -X GET \
  'https://api.tillhub.com/api/v1/products/{ clientAccountID }/?limit=100&deleted=false' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: YourJW-Token' \
  -H 'content-type: application/json;charset=UTF-8'
1
2
3
4
5

The limit query parameter (size can be used instead) sets the maximun number of product instances in a single page.

Another important query parameter is page. page stands for the page number within the iteration. The iterator of the pagination mechanism will position its cursor at page * limit

# Iterable resources response settings

While using the limit and page query paramters can paginate over the resources, each call to the paginated resources returns also a cursor JSON object. This cursor is essentially a set of ready made URLs which can be immediately used to iterate through pages. Note - the cursor URLs contain any other query paramters set in the initial call. they are injected to the cursor URLs as well.

A response object containing a cursor example:

{
  "status": 200,
  "msg": "Queried products successfully.",
  "request": {
      "host": "api.tillhub.com",
      "id": "26cdbe44-5ead-456e-b794-81b15ef770d9",
      "cursor": {
          "next": {
              "id": "2e8a5221-97af-4eb2-b02e-343361f0c139",
              "updated_at": "2021-04-09T14:55:17.419Z",
              "page": 2,
              "cursor_field": "updated_at"
          },
          "first": {
              "updated_at": "2021-06-11T09:16:50.697Z",
              "page": 0,
              "cursor_field": "updated_at"
          },
          "page": 1
      }
  },
  "cursor": {
      "first": "https://api.tillhub.com/api/v1/products/{ clientAccountID }?first=2021-06-11T09%3A16%3A50.697Z&page=0&size=100&cursor_field=updated_at",
      "self": "https://api.tillhub.com/api/v1/products/{ clientAccountID }?first=2021-06-11T09%3A16%3A50.697Z&page=1&size=100&cursor_field=updated_at",
      "next": "https://api.tillhub.com/api/v1/products/{ clientAccountID }?first=2021-06-11T09%3A16%3A50.697Z&page=2&size=100&cursor_field=updated_at"
  },
  "count": 100,
  "results": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

A few things to notice:

  1. The request contains a cursor field with the pagination settings specified.
  2. The cursor object contains three keys: first, self and next. Each value of these keys is a complete URL which can be used to call the first, next or current page (relative to the request pertaining to this cursor). In the example above, the api was called with page as 1, therefore the "first" URL has a page as 0, the "self" has a page as 1, and the "next" one has page as 2
  3. Two additional pagination settings are the "first" and "cursor_field" query paramters. They are optional but provide additional means to control the paginated outcome. first is the first date from which to fetch the results, and cursor_field will determine the main sorting field of the resource results.