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 a number of 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/notices \
  -d filter[created_at_gt]="2018-06-07"\
  -H "Authorization: Bearer 0526ff9fdbb3ca728daa3d17781eac1a15a1c3f0917abc53394d17ecdc8a8751"

Notice how the key for the ‘filter’ parameter is a combination of the created_at attribute and the _gt operator.

Filtering ‘Included’ Records

You can also apply these exact same filters against collections nested under a singular resource which you’ve included using the ‘?include’ parameter.

Here you have to submit a nested parameter within filter which corresponds to the name of the included collection, this, in turn, contains the filters for that collection.

This example request will return the requested page resource, but only the nested notices which were created after the given date.

curl -X GET https://api.sorryapp.com/v1/pages/:page_id \
  -d include="notices"
  -d filter[notices][created_at_gt]="2018-06-07"\
  -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"
*_neq The attribute does not equal the value provided. ?filter[subject_neq]="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]="2018-06-07"
*_lt The attribute is less than the value provided. ?filter[created_at_lt]="2018-06-07"
*_gte The attribute is greater than or equal to the value provided. ?filter[created_at_gte]="2018-06-07"
*_lte The attribute is less than or equal to the value provided. ?filter[created_at_lte]="2018-06-07"
*_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.