When searching for avatars, the result could embed thousands of avatars. To preserve time and network, the result is sent in pieces (subset of avatars). We call this subset //page//. It is the responsibility of the client to ask the result page per page.
Assuming a find request that returns N avatars indexed [0..N-1]. Remember that due to security reasons (usage of //ACL//), some avatars could be hidden.
Then in Thing in the future, a page is composed of
indexthe index of the first avatar,
page_sizethe number of maximum avatars,
sizethe number of visible avatars, then the number of avatars described into the data,
hiddenthe number of hidden avatars (by definition these avatars are not embedded into the data).
These numbers are return in the response : always into the http headers
Hidden-Items. They appear also in the body for the //application/json// response format as
To browse all the pages, the client should make a loop to get page after page by incrementing
index = 0 until
size + hidden < page_size. To go to the next page, at each step
index must be incremented with
The client has the possibility to retreive the total number of avatars returned by a find request by using the
/avatars/count endpoint. The returned number includes visible and hidden avatars.
Note : count only visible avatars is too expensive, it needs to process all the filtered avatars with their ACL. Then to preserve the platform against unnecessary and highly consumming tasks, we avoid it.
Consequently, it is possible for the client to compute the number of pages knowing this total number and the page size.