The REST API Query Language (RSQL) is a super-set of the Feed Item Query Language (FIQL) providing a way for parameterized filtering of entries in RESTful APIs using a clean and simple URI-friendly syntax.
Examples
/contracts?search=(country=='DE',country=='IT');startDate=gt='2023-01-01T00:00:00Z'&size=20&orderBy=startDate&direction=asc
/contracts?search=(country=='DE' or country=='IT') and startDate > '2023-01-01T00:00:00Z'&size=20&orderBy=startDate&direction=desc
Parameters
Our GET-endpoints usually support the following optional parameters:
search- the RSQL search query to filter entries by using different search criteria and operators.page- the page number to be returned, starting at 0.size- the number of entries to return for a page. A maximum of 100 is allowed.orderBy- order by criteriadirection- direction 'asc' or 'desc' for ordering.
Basic Operators
RSQL offers these basic operators:
| Operator (FIQL-style) | Alternative | Description |
|---|---|---|
| == | (n.a.) | Equal To |
| != | (n.a.) | Not Equal To |
| =gt= | > | Greater Than |
| =ge= | > = | Greater Or Equal To |
| =lt= | < | Less Than |
| =le= | > = | Less Or Equal To |
| =in= | (n.a.) | In |
| =out= | (n.a.) | Not in |
Multiple operators can be combined by joining them as follows.
Joining Operators
| Operator (FIQL-style) | Alternative | Description |
|---|---|---|
| ; | and | Logical AND |
| , | or | Logical OR |
By default, the AND operator takes precedence (i.e. it’s evaluated before any OR operators are). However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields.
Using the OR operator is not recommended to be used for automated integrations, as response times can be very long.
Dos and Don'ts when using RSQL
Wrapping and escaping the search
Please ensure to wrap the search parameter to ensure the best result. So search for
?search=orderIdent=='your_order'
instead of
?search=orderIdent==your_order
This also applies if you want to use wild cards - they should be part of the search string too, so
?search=orderIdent=='*order'
Wildcards currently do not work directly before or after underscores ('_').
Avoid spaces in your query
Please do not use any spaces when not needed, especially no leading or trailing spaces for properties to query for, eg.
?search= orderIdent == 'order123'
should be
?search=orderIdent=='order123'
The other way round using spaces around joining operators such as
?search=orderIdent=='order123' and grossTotal>100
is perfectly fine.
Querying by properties
Properties can be made use of for most of our resources (please check Properties for details), hence they can be targetted in queries as well:
/orders?search=(properties.propertyIdent=='orderChannel';properties.propertyValue=='MERCHANT')
Querying for multiple properties is currently not supported.