Filtering responsibilities between API resources and drivers¶
Keystone supports the specification of filtering on list queries as part of the
v3 identity API. By default these queries are satisfied in the API resource when
it calls the wrap_collection method at the end of a get method. However,
to enable optimum performance, any driver can implement some or all of the specified
filters (for example, by adding filtering to the generated SQL statements to generate
the list).
The communication of the filter details between the API resource and its drivers is handled by the passing of a reference to a Hints object, which is a list of dicts describing the filters. A driver that satisfies a filter must delete the filter from the Hints object so that when it is returned to the API, it knows to only execute any unsatisfied filters.
The contract for a driver for list_{entity} methods is therefore:
It MUST return a list of entities of the specified type
It MAY either just return all such entities, or alternatively reduce the list by filtering for one or more of the specified filters in the passed Hints reference, and removing any such satisfied filters. An exception to this is that for identity drivers that support domains, then they should at least support filtering by domain_id.
