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:

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{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: