Skip to content

Appendix

Paging the results

Some search results may be split into pages, and the response will look like the following:

{
    "elements": [
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}
The elements section contains data about the requested resource, while the page section contains pagination information with the following fields:

  • number: current page number
  • size: size of the requested page
  • totalElements: total number of found elements (optional not returned in all cases)
  • totalPages: total number of pages (optional not returned in all cases)

In each request involving pagination, the following parameters can be specified:

  • size: size of the requested page (default 20)
  • page: page number. The default value is 0, which corresponds to the first page

For example, to get the third page with size 10, you need to add the following parameters to the query:

size=10&page=2

Some search parameters allow the use of operators to refine the desired search.

These operators are expressed as <field>=<operator>:<value>.

As you can see the operator and the value are separated by the character ":".

The operators provide a variable number of values between 0 (no value) and N values. If multiple values are expected, they must be separated by comma (","). Examples:

  • no value: <field>=isNull:
  • one value: <field>=eq:123
  • two values: <field>=between:1,5
  • multiple values: <field>=in:a,b,c

The available operators are as follows:

Operator Value type Number of values
eq All 1
ne All 1
contains String 1
startsWith String 1
endsWith String 1
lt Number, Date, DateTime 1
le Number, Date, DateTime 1
gt Number, Date, DateTime 1
ge Number, Date, DateTime 1
isNull All 0
isNotNull All 0
between Number, Date, DateTime 2
in All 1-N
notIn All 1-N

Info

The documentation shows, for each field to be searched, the list of supported operators

Default operator

A default operator is defined for all search fields that support operators and this is the operator used if none is specified.

For example, if the org field has startsWith as the default operator, the two expressions are equivalent:

org=startsWith:Registro e org=Registro

Warning

If the separator character ":" is present in the search value, the default operator cannot be used, but the operator to be used must always be specified.

Example:

created=2024-01-03T12:30:00

is not valid expression and must be written as

created=eq:2024-01-03T12:30:00

Parameter cardinality

In some cases, search fields may be single, meaning they may appear once as a search parameter, or multiple, meaning they may appear multiple times.

Example of search with multiple parameters for resources created in 2023:

created=ge:2023-01-01&created=lt:2024-01-01

DateTime field

DateTime fields can be expressed either as date only or as full date and time. If the search value for a DateTime field contains only the date, it will be assumed to be a value at the beginning of the day. That is, the following expressions are equivalent:

created=ge:2024-01-01 e created=ge:2024-01-01T00:00:00