Paging
All list representations - e.g. representations that are list-like in form and contain several elements, such as assetlist, and collectionlist, are paged. Paging uses a request to the server to fetch only part of the list so the client can gradually scroll or "page" through the content.
If the list contains very few elements, the paging attribute can have the value null, indicating that paging is not available.
JSON format
paging: { prev: "", next: "/fotoweb/archives/5001-testarchive/;p=1", first: "/fotoweb/archives/5001-testarchive/", last: "/fotoweb/archives/5001-testarchive/;p=0" }
As shown above the paging attribute has links to previous and next pages, as well as first and last page.
Important
- Clients should not compute page URLs but use the available attributes above.
- Also, do no make assumptions about the number of elements per page. The number of elements may vary; using the attributes above FotoWeb will make the paging work as intended.
Note: Accept Headers / Media Types for collections
Accept header | Usage |
---|---|
application/vnd.fotoware.collection+json | This media type can only be requested for the first page of a collection. This is because the “collection” media type contains both a list of assets and a list of sub collections (folders), so it wouldn’t be clear which of those lists is being “paged”. |
application/vnd.fotoware.assetlist+json | Used for paging of the asset list |
application/vnd.fotoware.collectionlist+json | Used for paging of the sub collection list |
Paging Attributes
Attribute | Description |
---|---|
paging |
Paging information. If null, then the list is not paged, i.e., the representation contains the entire list. |
paging.next |
URL of next page. If |
paging.prev |
URL of previous page. If null, then there is no previous page, and the current representation is the first page. |
paging.first |
URL of first page. This attribute is never null and can be used for restarting navigation at the beginning of the list. |
paging.last |
URL of last page. If null, then the last page is not known, because it is not known how many pages there are. The last page (if the list has finite length) can be “discovered” by following paging.next repeatedly |
Notes
-
The attributes
paging.first
andpaging.last
have identical values on all pages, assuming that the contents of the list do not change during iteration -
If
paging
is notnull
for one page, then it is notnull
for any page. -
For the page retrieved from
paging.last
,paging.next
is null. -
For the page retrieved from
paging.first
,paging.prev
is null. -
Any page reached from a
paging.next
link has a non-nullpaging.prev
link that links back to its referrer, assuming that the contents of the list do not change during iteration -
Any page reached from a
paging.prev
link has a non-nullpaging.next
link that links back to its referrer, assuming that the contents of the list do not change during iteration
Note that the contents of some lists may change at any time, so it is recommended to not assume that paging.last
stays the same during iteration.
Important points
Clients should not make any assumptions about:
-
Whether or not a list is paged (i.e., they should always check if
paging
isnull
and act accordingly). -
Whether or not
paging.last
is null. -
The format of page URLs or the meaning of any parts it, including but not limited to, the order of page numbers (increasing or decreasing).
-
The number of elements of page, or whether or not different pages of the same list have the same number of elements.