Filtering & Pagination

Most endpoints that work with collections allow to filter and sort the results based on certain properties. This system is a powerful tool to save bandwidth and time by avoiding manual processing of the full result set.

Conditional Expressions

The filter is written as a JSON object and passed to the API through the query string (e.g., ?filter=...). This allows to create arbitrary logical conditions by nesting them.

Conditions

NameOperatorValueExample
Logical AND__andAn array of expression objects{"__and": [...]}
Logical OR__orAn array of expression objects{"__or": [...]}

Expressions

NameOperatorValueExample
Exact match__equal{"field": value}{"__equal": {"id": 1}}
Exact match (negated)__notEqual{"field": value}{"__notEqual": {"id": "foo"}}
Partial match__like{"field": value}{"__like": {"name": "rips"}}
Partial match (negated)__notLike{"field": value}{"__notLike": {"email": "%ripstech.com"}}
Null__null{"field": ""}{"__null": {"date":""}}
Null (negated)__notNull{"field": ""}{"__notNull": {"date":""}}
Comparison__greaterThan{"field": value}{"__greaterThan": {"age": 21}}
Comparison (inclusive)__greaterThanEqual{"field": value}{"__greaterThanEqual": {"price": 100}}
Comparison__lessThan{"field": value}{"__lessThan": {"price": 200}}
Comparison (inclusive)__lessThanEqual{"field": value}{"__lessThanEqual": {"price": "100"}}

All available fields are documented in the API specification.

Examples

Get all entities where the id is 1 or 2:

{
   "__or" : [
      {
         "__equal" : {
            "id" : 1
         }
      },
      {
         "__equal" : {
            "id" : 2
         }
      }
   ]
}


Get all entities where the id is 1 and the name is like "does%exist":

{
   "__and" : [
      {
         "__equal" : {
            "id" : 1
         },
         "__like" : {
            "name" : "does%exist"
         }
      }
   ]
}


A deep nested filter string:

{
   "__or" : [
      {
         "__equal" : {
            "id" : 13
         }
      },
      {
         "__equal" : {
            "id" : 42
         }
      },
      {
         "__and" : [
            {
               "__like" : {
                  "type" : "%_TAG"
               }
            },
            {
               "__notLike" : {
                  "type" : "CQ_%"
               }
            }
         ]
      },
      {
         "__or" : [
            {
               "__equal" : {
                  "name" : "name1"
               }
            },
            {
               "__and" : [
                  {
                     "__like" : {
                        "type" : "XSS%"
                     }
                  },
                  {
                     "__like" : {
                        "name" : "na%e"
                     }
                  }
               ]
            }
         ]
      }
   ]
}

Boundaries

Additionally, it is possible to limit the amount of elements in collections. Be aware that the default and maximum limit is 500, so to get all elements of large collections it is necessary to paginate over the results by increasing the offset. The HTTP header X-API-Pagination-More is included in the response if the number of elements matches the limit. This is usually a good indicator that more requests have to be done to get all results.

OperatorExample
limit/applications?limit=10
offset/applications?offset=20

Order

Results can be ordered by the same fields that can be filtered. The order-statement is written as a JSON object and passed to the API through the query string (e.g., ?orderBy=...). The keys of the object specify the fields, while the values specify the direction. The value can either be "asc" for ascending or "desc"  for descending (e.g., {"field1": "asc", "field2": "desc"}).

All available fields are documented in the API specification.

Select

To be done.