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
GET /api/resource?filter=name:eq:Example
{
"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)
GET /api/resource?filter=(price:gt:100,and,category:eq:Electronics)
{
"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)
GET /api/resource?filter=(company.name:eq:"Example Company")
{
"data": [
{
"id": 1,
"name": "Example",
}
],
...pagination data
}
Supported Operators#
The following operators are supported for filtering:gte
: Greater than or equal to
lte
: Less than or equal to
like
: Contains (case-insensitive)
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#
GET /api/resource?filter=price:gte:500
[
{
"id": 1,
"price": 600
}
]
Example 2: Multiple Filters with AND#
GET /api/resource?filter=(price:gte:500,and,category:eq:Electronics)
[
{
"id": 1,
"price": 600,
"category": "Electronics"
}
]
Example 3: Nested Filter#
GET /api/resource?filter=(company.name:eq:"Example Company")
[
{
"id": 1,
"name": "Example Name",
}
]
Modified at 2025-05-13 05:24:08