Pagination
NGSIv2 implements a pagination mechanism in order to help clients to retrieve
large sets of resources. This mechanism works for all listing operations
in the API (e.g. GET /v2/entities
, GET /v2/subscriptions
,
POST /v2/op/query
, etc.).
The mechanism is based on three URI parameters:
-
limit, in order to specify the maximum number of elements (default is 20, maximum allowed is 1000).
-
offset, in order to skip a given number of elements at the beginning (default is 0)
-
count (as
option
), if activated then aFiware-Total-Count
header is added to the response, with a count of total elements.
By default, results are returned ordered by increasing creation
time. In the case of entities query, this can be changed with the
orderBy
URL parameter.
Let's illustrate with an example: a given client cannot process more than 100 results in a single response and the query includes a total of 322 results. The client could do the following (only the URL is included, for the sake of completeness).
GET <orion_host>:1026/v2/entities?limit=100&options=count
...
(The first 100 elements are returned, along with the `Fiware-Total-Count: 322`
header, which makes the client aware of how many entities there are in total and,
therefore, the number of subsequent queries to be done)
GET <orion_host>:1026/v2/entities?offset=100&limit=100
...
(Entities from 101 to 200)
GET <orion_host>:1026/v2/entities?offset=200&limit=100
...
(Entities from 201 to 300)
GET <orion_host>:1026/v2/entities?offset=300&limit=100
...
(Entities from 301 to 222)
Note that if the request uses an offset beyond the total number of results, an empty list is returned, as shown below:
GET <orion_host>:1026/v2/entities?offset=1000&limit=100
...
[]
Ordering results
In the case of entities query, the orderBy
URL parameter can be used to
specify an order different from creation time. In particular, the value of
orderBy
is a comma-separated list of attributes and the results are ordered
by the first attribute. On ties, the results are ordered by the second attribute and so on.
A "!" before the attribute name means that the order is reversed. For example:
GET <orion_host>:1026/v2/entities?orderBy=temperature,!humidity
orders first by temperature in ascending order, then by humidity in decreasing order in the case of temperature ties.
Note that the special keywords dateCreated
and dateModified
can be used as
elements in the orderBy
comma-separated list (including the !
syntax) to mean
entity creation time and entity modification time respectively.