Paging and search

A list over a collection takes filter[<field>]=<value> (equality) or filter[<field>][<op>]=<value>, where in repeats the parameter; sort=<name> and direction=asc|desc; search; limit; cursor; count=true; and facets=<field>, repeated per field. A filter, sort or facet the collection does not declare is refused as invalid, never ignored.

It answers { items, cursor, total?, facets? }. While cursor is not null, a Link: <...>; rel="next" header names the next page.

Searching: an empty page with a cursor means nothing so far, not the end; only cursor: null ends a search. A searched page past the counting budget comes back without total and facets even when asked, which never means zero.

Other arguments of a read go in the query string: scalars as they are, objects one level deep (target[kind]=page&target[id]=...), arrays repeated, a reference as its id (product=<id>, or product=slug:<slug> where the kind has slugs).