Searching in the Whiplash API is very powerful, and pretty simple once you master a few things.

You can search each response according to its attributes, such as: 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.

Examples of Search Predicates

eq (equals)

The eq predicate returns all records where a field is exactly equal to a given value:

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)

The

cont_all

predicate returns all records where a field contains all of the given values:

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"}

Opposite: not_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