Abstract
-
Drops {index}. Defines {count}, {offset}, {page}
Status
Proposal
Rationale
Proposal
9. Collection List Templates
Collections can contain extremely large numbers of resources. A naive client such as a web spider or web browser would be overwhelmed if the response to a GET contained every entry in the feed, and the server would waste large amounts of bandwidth and processing time on clients unable to handle the response.
For this reason, Introspection documents refer to listings of collection members not with IRIs but with IRI templates contained in the "app:list-template" child of "app:collection". An IRI Template is a string containing one or more embedded tokens representing parameters used to limit the set of returned resources.
To produce an IRI that can be used to retrieve a partial or full listing of the members of a collection, each token may be replaced with an appropriate value for that particular token. An IRI template MUST, after such substitution has been performed, constitute a syntactically valid IRI.
This document defines three replacement tokens that MAY be used within IRI templates:
-
{count}: A non-negative integer value specifying the total number of resources to include in the list. If not specified, the value is determined by the server.
-
{offset}: A non-negative integer value specifying the offset at which to begin listing member resources. If not specified, the value is considered to be 0.
-
{page}: A non-negative integer value specifying a logical page index. Pages are subsets of results of a server-defined length. For instance, a server could define a page as including 20 collection members, each subsequent {page} value would return the next 20 members of the collection. In this case {page}=2 is equivalent to {count}=20 with {offset}=19. If not specified, the value is considered to be 0
None of the parameters are required. Servers MAY choose to specify additional tokens.
Replacement tokens may appear anywhere within the IRI template string and may be used together to form composite filters for lists.
For example, suppose the client is supplied this IRI template
http://example.org/entries/{page}?c={count}&o={offset}
If the client wants to return only the first five entries in the second page of results, it would substitute {page}=2, {count}=5, and {offset}=0 to achieve:
http://example.org/entries/2?c=5&o=0