RFC 008: API Filtering
Last updated: 19 October 2018.
Problem statement
To ensure a consistent developer experience across our APIs, we need to agree a set of patterns for filtering and sorting. This document outlines our approach.
Suggested solution
There are three complementary parts to this:
structured filtering
full text querying
sorting
Structured filtering
Structured filters are non-scoring (ie, they do not result in relevance scores) queries that can be used to restrict the resources returned, without influencing the order in which they are returned.
Structured filters have the following characteristics:
They are supplied as query parameters
They have the name of the property they are used filter
Multiple query parameters are combined using
AND
Multiple comma (
,
) separated values within a single query parameter are combined usingOR
Closed-open ranges are supported using
/
Dotted syntax is used to specify paths
id
is implicit in parameter paths
Examples:
Filter for a single work type:
Filter for multiple work types:
Filter for multiple work types with a single subject:
Filter for multiple work types with a multiple co-occurring subjects:
Searching within structured data within structured filtering
Full text querying
Full text querying is supported as a scoring query that can be used to restrict the resources returned, by default returning them in relevance order.
Full text querying has the following characteristics:
It is supplied as a single query parameter
The query parameter is called
query
It can be combined with any combination of structured filters
Some field based and other advanced full text querying may be supported, but is service dependent
Examples:
Find all works that mention skeletons:
Find all works that mention skeletons and are books or ebooks:
Sorting
The default ordering for a collection of resources is service dependent. It can also vary for different kinds of resource within the same service, to ensure that the default ordering is the most appropriate in the majority of cases.
In addition to this:
Use of full text querying should change the default order to ordering by relevance
This can be overridden using a
sort
parameterThe value of this parameter is a comma separated list of properties
The order within a property can be changed using
asc
anddesc
modifiers
Example:
Last updated