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
index the index of the first avatar,page_size the number of maximum avatars,size the number of visible avatars, then the number of avatars described into the data,hidden the 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 Index, Page-Size, Size and Hidden-Items. They appear also in the body for the //application/json// response format as index, page_size, size and hidden.
To browse all the pages, the client should make a loop to get page after page by incrementing index from index = 0 until size + hidden < page_size. To go to the next page, at each step index must be incremented with page_size.
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.