Paging and search

A list over a collection takes filter[<field>]=<value> (equality) or filter[<field>][<op>]=<value>, where in repeats the parameter (filter[section][in]=Design%2C%20Research&filter[section][in]=Other); 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 (span[from]=...), arrays repeated (ids=a&ids=b), a reference as its id (product=<id>, or product=slug:<slug> where the kind has slugs). A read whose arguments are deeper is a POST to its /query path with a JSON body.