Searching in the Whiplash API is very powerful, and pretty simple once you master a few things.
You can search pretty much any attribute available via the API, like order["shipping_city"], item["sku"], or order_item["quantity"].
You combine the attribute with one of the predicates below to create filters like "shipping_city_matches", "sku_start", or "quantity_gt".
You can search a resource's associations. For instance, an order has order_items. So, you can search an order using "order_items_sku_start".
Here is an example of each search predicate in action:
eq (equals)
GET /api/v2/orders?search={"email_eq": "customer@gmail.com"}
Opposite: not_eq
matches
The matches predicate returns all records where a field is like a given value:
GET /api/v2/orders?search={"shipping_city_matches": "ANN arbor"}
Opposite: does_not_match
Note: If you want to do wildcard matching, you may be looking for the cont/not_contpredicates instead.
lt (less than)
The lt predicate returns all records where a field is less than a given value:
GET /api/v2/orders?search={"status_lt": 300}
Opposite: gteq (greater than or equal to)
lteq (less than or equal to)
The lteq predicate returns all records where a field is less than or equal to a given value:
GET /api/v2/orders?search={"shipped_on_lteq": '2017-11-25 00:00:00'}
Opposite: gt (greater than)
in
The in predicate returns all records where a field is within a specified list:
GET /api/v2/orders?search={"status_in": [300, 350]}
Opposite: not_in
cont
The cont predicate returns all records where a field contains a given value:
GET /api/v2/items?search={"title_cont": "shirt"}
Opposite: not_cont
cont_any (contains any)
The cont_any predicate returns all records where a field contains any of the given values:
GET /api/v2/orders?search={"order_items_description_cont_any": ["CD", "LP", "Cassette"]}
Opposite: not_cont_any
cont_all (contains all)
GET /api/v2/orders?search={"order_items_description_cont_all": ["LP", "Deluxe"]}
Opposite: not_cont_all
start (starts with)
The start predicate returns all records where a field begins with a given value:
GET /api/v2/items?search={"sku_start": "SKU-XX"}
Opposite: not_start
end (ends with)
The end predicate returns all records where a field ends with a given value:
GET /api/v2/items?search={"sku_end": "-SM"}
Opposite: not_end
true
The true predicate returns all records where a field is true. The '1' indicates that you indeed want to check the truthiness of this field. The other truthy values are 'true', 'TRUE', 't' or 'T'.
GET /api/v2/items?search={"promo_true": "true"}
false
The false predicate returns all records where a field is false.
GET /api/v2/items?search={"packaging_false": "true"}
Opposite: not_false
Note: the false predicate may be considered the opposite of the true predicate if the field does not contain null values. Otherwise, use not_false.
present
The present predicate returns all records where a field is present (not null and not a blank string).
GET /api/v2/shipnotices?search={"tracking_present": "true"}
Opposite: blank
null
The null predicate returns all records where a field is null:
GET /api/v2/orders?search={"public_notes_null": "true"}
Opposite: not_null