4.4.16. Using Entities Search Filter

REST API allows you to specify ad-hoc search criteria when getting a list of entities.

Let’s suppose that we have two entities:

  • Author that has two fields: lastName and firstName

  • Book with three fields: title (String), author (Author) and publicationYear (Integer)

To perform a search with conditions we must use the URL like this:

http://localhost:8080/app/rest/v2/entities/test$Book/search

The search conditions must be passed in the filter parameter. It is a JSON object that contains a set of conditions. If the search is performed with the GET request, then the filter parameter must be passed in the URL.

Example 1

We need to find all books that were released in 2007 and have an author with the first name starting with "Alex". The filter JSON should look like this:

{
    "conditions": [
        {
            "property": "author.firstName",
            "operator": "startsWith",
            "value": "Alex"
        },
        {
            "property": "publicationDate",
            "operator": "=",
            "value": 2007
        }
    ]
}

By default, search criteria are applied with the AND operation.

This example also demonstrates that nested properties are supported (author.firstName).

Example 2

The next example demonstrates two things: how to execute a search with the POST request and how to use OR groups. In case of POST request all parameters must be passed in the JSON object that is passed in the request body. The search filter must be placed in the object field called filter. All other parameters (view name, limit, etc.) must be placed in fields with corresponding names:

{
  "filter": {
    "conditions": [
      {
        "group": "OR",
        "conditions": [
          {
            "property": "author.lastName",
            "operator": "contains",
            "value": "Stev"
          },
          {
            "property": "author.lastName",
            "operator": "=",
            "value": "Dumas"
          }
        ]
      },
      {
        "property": "publicationDate",
        "operator": "=",
        "in": [2007, 2008]
      }
    ]
  },
  "view": "book-view"
}

In this example, conditions collection contains not only condition objects, but also an OR group. So the result search criterion will be:

((author.lastName contains Stev) OR (author.lastName = Duma) AND (publicationDate in [2007, 2008]))

Notice that the view parameter is also passed in the request body.