API search

Certain API endpoints, which list resources, can take a search string for filtering the returned elements. The search string is a comma-separated list of search conditions. A search condition consists of a key, an operator and a value.

Search string

The search string is presented to the API endpoint as a query parameter named search. A search string is one or more search conditions separated by commas. A search condition constructs from a search key, a search operator and a search value.

Every search key corresponds to a data type. The corresponding data type determines the available search operators and values. Search keys and the connected data types are listed in the documentation of the individual API endpoints.

Search operators

Search operators are represented with single characters in the search condition. Wenenu supports five search operators: :, !, >, <, ~.

Name Operator Description

Equality

:

Lists elements where the search key is equal to the search value

Negation

!

Lists elements where the search key is not equal to the search value

Greater than

>

Lists elements where the search key is greater than the search value

Less than

<

Lists elements where the search key is less than the search value

Like

~

Lists elements where the search key is like the search value

The following search condition looks for elements where the name is equal to 'Test':

name:Test

The following API call lists the first 20 test scenarios where the name is equal to 'Test':

GET https://wenenu.com/manage/scenarios?offset=0&limit=20&search=name:Test HTTP/1.1

Like operator

The like (~) operator is used for searching string data types. When the like operator is used, the search value can start and end with an asterisk (*) character. If the search value ends with an asterisk character then the search key must start with the given search value. If the search value starts with an asterisk character then the search key must end with the given search value. If the search value starts and ends with asterisk characters then the search key must contain the given search value.

The following search condition looks for elements where the name starts with the string 'test':

name~test*

The following search condition looks for elements where the name ends with the string 'test':

name~*test

The following search condition looks for elements where the name contains the string 'test':

name~*test*

Search key types

UUID type

The UUID type is for searching Wenenu resource IDs. The search value must be a valid version 4 UUID string. The available operators are equality (:) and negation (!). The following search condition looks for elements where the ID is not the given UUID:

id!1fec730e-3e63-428c-a3dc-9b88d8b4d318

String type

The string type is for searching free text values such as names, descriptions, etc. The search value can be an arbitrary string. The available operators are equality (:), negation (!), greater than (>), less than (<) and like (~). The following search condition looks for elements where the name is greater than 'alpha':

name>alpha

Integer type

The integer type is for searching whole number values. The search value can be an arbitrary string representation of an integer number. The available operators are equality (:), negation (!), greater than (>) and less than (<). The following search condition looks for elements where the version is less than 5:

version<5

Boolean type

The boolean type is for searching values that can be either TRUE or FALSE. The search value can be a 'true' or 'false' string. More precisely, every case insensitive 'true' string is evaluated to TRUE, everything else is FALSE. The available operators are equality (:) and negation (!). The following search condition looks for elements that are not scheduled:

scheduled:false

DateTime type

The DateTime type is for searching values that represent a moment in time. Search values must be ISO-8601 date-time format strings, for example, '2011-12-03T10:15:30'. Optionally, a positive or negative timezone offset can be attached as a suffix to the date-time string, for example, '2011-12-03T10:15:30+01:00'. If the offset is omitted, the given date-time is evaluated in the UTC timezone. The available operators are equality (:), negation (!), greater than (>) and less than (<). The following search condition looks for elements where the last started time is later than the given date-time in the UTC timezone:

lastStarted>2011-12-03T10:15:30
Note The plus sign is used as shorthand for a space in query parameters. The plus sign in the date-time string with positive offset needs to be properly encoded as %2b, unless it will be parsed as a space.

OR condition

By default, search conditions are evaluated with an AND operator between them. The following search string looks for elements that are scheduled and their name is 'Test':

scheduled=true,name:Test

Adding a single apostrophe (') character in front of a search condition joins the condition with the OR operator. The following search string looks for elements that are scheduled or their name is 'Test':

scheduled=true,'name:Test

Limitations

The way how the search conditions are constructed places some restrictions on the search values:

  • Search values cannot contain commas

  • Search values cannot start or end with an asterisk character