Implement paged repsonse

[Patrick]

Whenever a page result is responded to a client, the Pagination Information has to be sent with the response:

Paging

Every GET request is filterable by using the request parameter $offset and $limit. Using these parameters, a list response can be offset by $offset and limited to a total length of $limit. E.g. GET /tuner/stations?$offset=5&$limit=10 returns a list of 10 elements in total, starting with the 6th (lists start with index 0) element, closing with the 15th element. Both parameters are applicable for events and requests. The response and event payload may contain a paging property to help the client determining the previous and next page of results.

$offset can be either an integer value or an uuid. E.g. GET /tuner/stations?$offset=932e5b1e-1848-11e5-b60b-1697f925ec7b&$limit=10 returns a list of 10 elements in total, starting with the element 932e5b1e-1848-11e5-b60b-1697f925ec7b.

$limit can be any positive or negative integer. Negative values will return a list of elements before the $offset, $offset being the last element, positive values let the returned list start at $offset.

Retrieve from the end of a list

To retrieve a list backwards a client might use a query with negative $limit AND negative $offset. The index -1 marks the last element of a list. E.g. GET /tuner/stations?$offset=-1&$limit=-10 will return the last 10 last, $offset=-1 marks the last element.

Paging is not only available on resource level but also on nested lists, even though paging nested lists does not tell the client about the previous and next page. Paging nested lists is only possible together with $fields filtering by adding ($offset:<offset>,$limit:<limit>) to the expanded or filtered property name in the query string, link in /addressbook/contacts/?$fields=emails($offset:0,$limit:2).

Service initiated paging

In case of queries that can not be answered at once, a service may send a partial result with paging information attached. E.g. if a client queries /navigation/pois (without any filters), the result list might be too big to transfer, so the service will initiate the paging of the result itself, by sending a certain number of results and setting the paging properties accordingly.

Responses shall contain a paging section for paged results

{
  "type" : "data",
  "event" : "/<service>/<resource>/<element>?<query-params>#<uniqueid-per-session>",
  "data": <payload>,
  "paging" : {
    "total": Integer,
    "totalPages": Integer
  },
  "timestamp": Integer
}

or

{
  "type" : "data",
  "event" : "/<service>/<resource>?<query-params>#<uniqueid-per-session>",
  "data": <payload>,
  "paging" : {
    "previous" : "/<service>/<resource>?$limit=<limit>&$offset=<previousoffset>#<uniqueid-per-session>",
    "next" : "/<service>/<resource>?$limit=<limit>&$offset=<nextoffset>#<uniqueid-per-session>",
    "total": Integer,
    "totalPages": Integer
  },
  "timestamp": Integer
}