Filter Pattern

The Filter pattern provides filtration affordances. It often complements List and Tree patterns but can also be used to filter any resource that has elements with filterable aspects. The Filter pattern has a Filter Info resource that describes the filter configuration. Clients can change the filter configuration with the Filtration resource. The elements in the resource should share the filterable properties for the Filtered resource to make sense to the client.

Filter Configuration

The client changes filter configuration by POSTing a new configuration lookup to the Filtration resource. Filtration returns the updated Filtered resource URI in its location response header.

Operands

Filter declarations use logical operands to describe how to filter the elements by property values. String value comparisons should be case-insensitive if possible, though the resource implementation decides this rule based on the field’s semantics. The resource’s data types guide the applicability of these operands to filtered fields.

These operands work efficiently with indexed data and should provide quick client responses.

Filtered Resource

profile: <https://level3.rest/patterns/filter#filtered-resource>

The Filtered resource can present any profile. The profile choice does not effect filtering options.

filter-info

rel="https://level3.rest/patterns/filter#filter-info"

Points to a Filter Info resource that describes the filtered resources filtering configuration.

Filter Info Resource

profile: <https://level3.rest/patterns/filter#filter-info-resource>

The Filter Info resource describes the current filtering configuration used in the Filtered resource. The configuration representation consists of an array of filter declarations assigned to a top-level filters element.

A filtering declaration in the filters array has these properties:

Each filter declaration further filters the elements by that declaration. The array of declarations ANDs together to create an element list that matches every filter. Consider this filters array:

{
  "filters": [
    { "property": "age", "operand": "gte", "value": 30 },
    { "property": "team", "operand": "in", "value": ["Bruins", "Canucks"] }
  ]
}

The filtered resource contains elements filtered by age (>= 30) and a team of either “Bruins” or “Canucks”.

The XML representation looks like this:

<filters>
  <filter property="age" operand="gte" value="30"/>
  <filter property="team" operand="in">
    <value>Bruins</value>
    <value>Canucks</value>
  </filter>
</filters>

filter

rel="https://level3.rest/patterns/filter#filter"

Points to a Filtration resource that configures the filtration of the Filtered resource.

Filtration Resource

profile: <https://level3.rest/patterns/filter#filtration-resource>

The Filtration resource changes the Filtered resource’s filtration configuration. It is a Lookup resource that starts with the current configuration in its schema representation, or its template object if the lookup does not use a schema. If only a subset of the properties are filterable, then the Filtration resource should present a schema to help the client submit a successful filtration change.

A Filtration’s content is the same as the Filter Info content. Clients edit the configuration to reflect the desired filtration configuration. When this new configuration is submitted to the Filtration resource, the lookup redirects to the newly-configured Filtered resource.

filters

rel="https://level3.rest/patterns/filter#filters"

Points to the Filtered resource that this Filtration resource filters.

© 2019-2023 Matt Bishop

This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.

Tweet about Level 3 REST