This document describes the client side interfaces which a developer can use to Page through data obtained from remote rest services. This document describes both how to interact with the Aerogear-Controller based paging as well how to extend the client libraries and APIs to support most other restful services.
At a high level, Paging is supported through the Pipe’s
read method (see the platform API doc, for specific details).
In order to start a paging request, the API needs to accept a configuration setting, which sets the offset of the first element that should be included in the returned collection (
offset) and the number of results that should be listed on a page (
limit). The different platform SDKs may support different ways to apply the paging configuration (see the platform API doc, for specific details).
The actual Pipe implementation will be responsible for processing a request along with any paging data and sending the appropriate headers, data, and query parameters to the server (see Server API spec). Once the response has been received, the Pipe implementation will provide the result to the supplied callback (see the platform API doc, for specific details).
An object to apply general information about a (paging) request.
identifiers) is received from the response
header, the response body (
body) or via RFC 5988 (
webLinking), which is the
nextidentifier name (default:
previousidentifier name (default:
NOTE: The AeroGear-Controller uses the Web Linking API for this.
The paging parameters can be defined on the Pipe and on the paging request. For instance an initial default (e.g. list always 15 items per page and always start at the second page) works fine on the Pipe. The Pipe is responsible to maintain the paging requests (e.g.
previous), by using the given
However, it should be always possible for a user to update the arguments on a per request base. For instance if the application needs to show for a specific reason
20 items instead of the 15 from the beginning. Another reason could be the server does not support the above discussed
identifiers, so the application developer needs to maintain the next and previous information.
parameter provider API will be provided to that the application developer can submit any (paging) parameter that the used server requires. An example would be that the used paging service supports sorting as well.
In order to navigate through a large data set, the following methods are required. The actual implementation can be different, based on the used SDK (see the platform API doc, for specific details).
NOTE: When scrolling outside of the allowed range (e.g. invoking
next on the last page), the client should be able to handle any success response, whether there is data or not, and also any error response.
paged read(see concrete API docs for details)
lastpage - if possible/desired
offsetto the desired page, e.g
previous, if possible…)