22 Filtering
This chapter covers...
- Why standard List methods should support filtering resources
- How to communicate a filter expression as part of the standard List request
- Guidelines for behavior when filtering resources
- Functionality that should and should not be supported in filter conditions
While the standard List method provides a mechanism to iterate through a complete set of resources in an API, so far we really don't have a way to indicate an interest in only a subset of those resources. This pattern will explore using a special field on the standard List request as a way to apply a filter on the full data set to return only a matching result set. Additionally, we'll get into the details of how to structure input values for this special filtering field.
22.1 Motivation
So far, the typical way of retrieving lots of resources has been pretty straightforward: use the standard List method. Similarly, if we're looking for a specific resource and happen to know its identifier, we have an equally straightforward tool at our disposal: the standard Get method. But what if our goals fall somewhere in between? What if we want to browse through resources that happen to match a specific set of criteria? We're neither looking for an individual resource, nor are we aiming to browse through all resources, but we do have some idea of the resources we're searching for. How can we handle this?