Pagination

The API allows you obtaining the response to a search in blocks with predefined number of results.

  • limit:
    • start: Page number you request. The count starts with the number 1
    • size: The number of entities that you can see on the page
Default number of items returned

The search API limits the page size to 50 items by default, but you probably have thousands of devices. How do you walk through all your devices?.

Well, let’s suppose you have exactly 2500 devices matching your query. Obviously, your result exceeds the default limit. In this case, you’ll find a page object in your response.

Paginated examples

Paginated example response

{
    "page" : { "number" : 1 },
    "resources" : [
        { ... },
        { ... },
        { ... },
        { ... },
        ...
        { ... }
    ]
}

Warning about the previous example

Warning

Please, take the resources field on the previous example as a placeholder for any reserved word into the scope of the searched resource: entities, devices, subscriptions, data models, bundles, data streams, data points, etc.

The number attribute is the current number of pages based on the limit setup.

What can you do to get the following page? It’s easy. You only have to include a limit object in your query. See next example.

Pagination example request

{
  "limit": {
    "start": 2
  }
}

Paginated example generic response

{
   "page" : { "number" : 2 },
   "resources" : [
       { ... },
       { ... },
       { ... },
       { ... },
       ...
       { ... }
   ]
}

See previous warning about the resources word in the example.

You can change the page limit from the beginning. Supposing you want to retrieve 50 items per query, you must set up the limit object with a starting point and the page size you want.

Paginated example request

Changing the starting page and the limit

{
  "limit": {
    "start": 2,
    "size": 50
  }
}

The top margin for the page size in the limit object is 1000. You’ll receive a server error response if you set up a size attribute over this limit.

Another example of pagination response

With the starting page and the limit changed

{
    "page" : { "number" : 2},
    "resources" : [
         { ... },
         { ... },
         { ... },
         { ... },
         ...
         { ... }
    ]
}

See previous warning about the resources word in the example.