Search Criteria

Overview

Being able to search and filter data is an important part of any API. In newly added endpoints, we've made it possible to search information, by defining filters presented in a query string, that conforms to a schema we created and support.

While we will endeavour to update existing endpoints to support search criteria, it will take some time and effort. Until then, only endpoints that explicitly mention support will have the ability to use it.

Pagination

A lot of the time, when you're making calls to the Cabinetry.Online API, there'll be a lot of results to return. For that reason, we paginate the results to make sure responses are performant and easier to handle.

Let's say your initial call is asking for all the customers; the result could be a massive response with hundreds of thousands of pages. That's not a good place to start.

Rather than that, we've built in a default limit on results, but we recommend you always explicitly set the page_size parameter to ensure you know how many results per page you'll get. Don't rely on the defaults as they'll be different depending on what parts of the response you're expanding, so the response you get might not be what you expected.

For example, you might need to request all customers associated with your account, but you only want the results 5 at a time. Your GET request would look something like this:

curl -X GET 'https://cabinetry.online/api/admin/customers?page_size=5' -H 'X-GC-API-KEY: xxxxxxxxxxxx'

Note the page_size parameter in this call is set to 5, so the response would show items 0 through to 5.

{
    "success": 1,
    "items": [
        {
            "id": 1234,
            "manufacturer_id": 7891,
            "name": "John Doe Kitchens",
            "email": "john@example.com",
            "telephone": "0480123456",
            "cc_email": "harry@example.com",
            "price_adjustment": 0,
            "minimum_charge": 30,
            "minimum_freight": 0,
            "address": {
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "postcode": "3268",
                "country": "Australia"
            },
            "settings": {
                "assembly_enabled": false,
                "is_beta": true,
                "is_premium": true
            }
        },
        {},
        {},
        {},
        {}
    ],
    "pagination": {
        "current_page": 1,
        "page_count": 10,
        "page_size": 5,
        "total_count": 46
    }
}

In the above response, you may notice it contains pagination information helping to iterate further over records. You can assume if the current_page is less than page_count, further information is available. To retrieve the next page of results, your GET request would look something like this:

curl -X GET 'https://cabinetry.online/api/admin/customers?current_page=2&page_size=5' -H 'X-GC-API-KEY: xxxxxxxxxxxx'

Filters Groups

Filter groups are defined as part of the query string, which wraps the filters wanting to be applied.

curl -X GET 'https://cabinetry.online/api/admin/customers?filter_groups=((<field>:<condition>:<value>))' -H 'X-GC-API-KEY: xxxxxxxxxxxx'

Often, when wanting to search or narrow down the results, multiple or complex criteria is required. Filter groups allow compounding filters to be applied, to the same field or and entirely different field. As an example, lets assume we are searching for any customer with the name John, who resides in the state of Victoria. Your GET request would look something like this:

curl -X GET 'https://cabinetry.online/api/admin/customers?page_size=5&filter_groups=((name:contains:John) AND (state:equals:Victoria))' -H 'X-GC-API-KEY: xxxxxxxxxxxx'

Note multiple filters are separated with the word AND between parenthesis.

{
    "success": 1,
    "items": [
        {
            "id": 1234,
            "manufacturer_id": 7891,
            "name": "John Doe Kitchens",
            "email": "john@example.com",
            "telephone": "0480123456",
            "cc_email": "harry@example.com",
            "price_adjustment": 0,
            "minimum_charge": 30,
            "minimum_freight": 0,
            "address": {
                "street": [
                    "123 Summer St"
                ],
                "suburb": "Boggy Creek",
                "state": "Victoria",
                "postcode": "3268",
                "country": "Australia"
            },
            "settings": {
                "assembly_enabled": false,
                "is_beta": true,
                "is_premium": true
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "page_count": 1,
        "page_size": 5,
        "total_count": 1
    }
}

Filters

A filter consists of:

• field is an attribute name.
• condition one of many filter conditions available.
• value specifies the value to search for.

Conditions

Below is a list of conditions available along with their example usage.

Date Presets

Below is a list of date presets available. They can be quite useful when fetching information or generating reports by a date relative in time. For example, generating reports for accounts/invoices between financial years or quarterly.

Note: Regarding the before and after prefixes. Presets prefixed with before will search for values less or equal to the field value. Whereas presets prefixed with after will search for values greater or equal to the field value.

Note: Regarding the start and end suffixes. Presets suffixed with start automatically have the date adjusted to the beginning of its period (day, week, month, year) with time set as 00:00. Whereas presets suffixed with end automatically have the date adjusted to the end of its period (day, week, month, year) with time set as 23:59.