We provide a generic way to filter and search results whenever making a GET request to a resource which returns a collection of records.
When listing records, you’ll often only want to return those which match certain criteria, such as listing all the notices of a given type or those created after a certain date.
The ‘Filter’ Parameter
This is done using the ‘filter’ parameter on the request. This parameter can contain several keys, which are the combination of the attribute name and operator, followed by the value.
The following example only returns notices with a created_at date greater_than the given date.
curl -X GET https://api.sorryapp.com/v1/pages/:page_id \
-d include="notices"
-d filter[notices][created_at_gt]="2022-05-30"\
-H "Authorization: Bearer 0526ff9fdbb3ca728daa3d17781eac1a15a1c3f0917abc53394d17ecdc8a8751"
Notice the new nested parameter filter[notices] which matches that passed in the ?include=notices parameter.
Available Operators
The examples above both use the *_gt operator, but there are lots of other useful operators you can use in much the same manner.
| Operator | Description | Example |
|---|---|---|
| *_eq | The attribute equals the value provided. | ?filter[subject_eq]=“Database Maintenance” |
| *_not_eq | The attribute does not equal the value provided. | ?filter[subject_not_eq]=“Database Maintenance” |
| *_matches | The attribute partially matches the value LIKE. | ?filter[subject_matches]=“%Maintenance” |
| *_cont | The attribute contains the value. | ?filter[subject_cont]=“Maintenance” |
| *_gt | The attribute is greater than the value provided. | ?filter[created_at_gt]=“2022-05-30” |
| *_lt | The attribute is less than the value provided. | ?filter[created_at_lt]=“2022-05-30” |
| *_gteq | The attribute is greater than or equal to the value provided. | ?filter[created_at_gteq]=“2022-05-30” |
| *_lteq | The attribute is less than or equal to the value provided. | ?filter[created_at_lteq]=“2022-05-30” |
| *_present | The attribute is not blank or empty. | ?filter[began_at_present] |
| *_blank | The attribute is blank or empty. | ?filter[began_at_blank] |
| *_in | The attribute is contained in the list provided by the value. | ?filter[type_in]=“planned”&filter[type_in]=“unplanned” |
| *_not_in | The attribute is not contained in the list provided by the value. | ?filter[type_not_in]=“planned”&filter[type_not_in]=“unplanned” |
Filtering your API requests to only include the records you need is a great way to increase performance and also cut down on the amount of bandwidth needed. For a real-world example, take a look at the requests made by our very own website plugin.