Filter

The API supports an advanced filtering system using the filter query parameter, which allows clients to specify complex filtering logic. This feature enables precise and efficient querying of resources based on multiple conditions and nested relationships.

Filter Syntax

Filters are defined using the filter parameter in the query string. The format supports logical operators (AND, OR), nested conditions, and a variety of comparison operators.

Basic Filter

To apply a simple filter:

GET /api/resource?filter=field:operator:value

Example:

GET /api/resource?filter=name:eq:Example

Response:

{
    "data": [
        {
            "id": 1,
            "name": "Example"
        }
    ],
    ...pagination data
}

Multiple Filters

Combine filters using logical operators (AND, OR) and parentheses for grouping:

GET /api/resource?filter=(field1:operator1:value1,and,field2:operator2:value2)

Example:

GET /api/resource?filter=(price:gt:100,and,category:eq:Electronics)

Response:

{
    "data": [
        {
            "id": 1,
            "price": 150,
            "category": "Electronics"
        }
    ],
    ...pagination data
}

Nested Filters

Use dot notation to filter based on related resources:

GET /api/resource?filter=(related_resource.field:operator:value)

Example:

GET /api/resource?filter=(company.name:eq:"Example Company")

Response:

{
    "data": [
        {
            "id": 1,
            "name": "Example",
        }
    ],
    ...pagination data
}

Supported Operators

The following operators are supported for filtering:

eq: Equals

ne: Not equals

gt: Greater than

lt: Less than

gte: Greater than or equal to

lte: Less than or equal to

like: Contains (case-insensitive)

starts_with: Starts with

ends_with: Ends with

in: Value in a list (semicolon-separated)

not: Negates the filter condition

Behavior Notes

Logical operators (AND, OR) are case-insensitive.

Fields used in the filter do not require to be in show or with.

If an invalid operator is provided, the API will return a 400 Bad Request response with details of the error.

Examples

Example 1: Single Filter

Request:

GET /api/resource?filter=price:gte:500

Response:

[
  {
    "id": 1,
    "price": 600
  }
]

Example 2: Multiple Filters with AND

Request:

GET /api/resource?filter=(price:gte:500,and,category:eq:Electronics)

Response:

[
  {
    "id": 1,
    "price": 600,
    "category": "Electronics"
  }
]

Example 3: Nested Filter

Request:

GET /api/resource?filter=(company.name:eq:"Example Company")

Response:

[
  {
    "id": 1,
    "name": "Example Name",
  }
]

Filter Syntax#

Basic Filter#

Multiple Filters#

Nested Filters#

Supported Operators#

Behavior Notes#

Examples#

Example 1: Single Filter#

Example 2: Multiple Filters with AND#

Example 3: Nested Filter#

Filter Syntax

Basic Filter

Multiple Filters

Nested Filters

Supported Operators

Behavior Notes

Examples

Example 1: Single Filter

Example 2: Multiple Filters with AND

Example 3: Nested Filter