The current search options for APIs are complex and cover only limited scenarios.

The query string can quickly become complex for simple operations like checking conditions or checking for a value between two dates.

Along with the search parameters, there are also other commands we generally use to alter the behaviour of the API execution. These commands could be related to, for example, sorting the data, returning a maximum number of records or pagination.

We also thought about other capabilities, like debugging the API execution in real-time or, in specific scenarios, being able to skip the cache and hit the backend database directly.

Along the same lines, it would be nice to bring in some information related to the child and other linked records (TRIRIGA being Object Oriented, we have numerous linked objects). This capability helps immensely in scenarios when we only must display limited information from the related records.

While designing the search and data control feature, ease of use was the primary concern. Therefore, we were looking to in-built a wide range of operators to help extract the data simply and consistently. Furthermore, these operators are extendible as per the usage requirements in future.

Query Parameter: (represented by “q”)

We created a “Query Parameter” option to seamlessly handle the complex search options.

The Query Parameter consists of the following Operators:

Logical Operators - allows logical commands, for example, “Contains”, “Starts with”, “Equals”, “Not Equals”, and “In”. We can combine these operators with the “And” or “Or” conditions to create complex logical commands.

Conditional Operators - allows conditional commands, for example, “Greater than”, “Greater than or Equals”, “Less than”, “Less Than or Equals”, and “Between”.

Date Operators - allows date-related commands, for example, “Between two dates”, “Start of the day”, “Start of next day”, “Start of the day before”, “Start of this week”, “Start of next week”, Start of previous month”, to name a few. The date operator utilises conditional and additional date operators along with the shortcut keywords to achieve the desired results.

We can combine the individual operators under the “Query Parameter” grouping to cater to more complex search scenarios.

How do these Operators work?

All operators become part of the query string in a pre-defined structure. The query parameter has a JSON syntax and can enable complex searches.

Let’s take a use case: A user would like to search for a person called “John” in any city called “Boston”.

The search query parameter (represented by “q”) will be like this:

q={"_and":[{"firstName":{"_equals":"John"}},{"city":{"_contains":"Boston"}}]}

Similarly, we can combine other operators to fulfil multiple use cases: A number is greater than a value:

q={"numberOfHours":{"_gt":"10"}}

A date between two dates:

q={"submittedOn":{"_bt":["2022-12-01T09:00:00+01:00", "2022-12-05T17:00:00+01:00"])}

Or one can combine the keywords as shown below to achieve similar results as above:

q={"submittedOn":{"_bt":["_today", "_now"])}

The API Explorer tool has all these operators available through a friendly UI to select and construct the query you want to use.

Main Query Operators:

The core Query Operators are “Logical”, “Conditional”, and “Date”. A combination of these operators, along with “And” or “Or” operators, gives us multiple combinations for search.

In the API Explorer, API Consumers can easily construct the Query parameter JSON structure.

Logical Operators:

The Logical operators allow us to add logical commands to the search query. We can use a combination of these operators to achieve the desired result.

The Contains operator will allow a SQL-like search for any partial values.

The Starts operator will allow a SQL-like search for a record where the specific field value starts with the value provided in the search.

The Equals operator will check for an exact match for the value, including proper case matching.

The Not Equals operator will check if the exact value doesn’t match the field value. This operator also performs case-sensitive matches.

The In operator will check for the values within a list of values for an exact match.

The above operators can be combined with the “And” or “Or” operators to achieve the desired results. Only one of the “And” or “Or” operators can be used at a given time.

Conditional Operators:

The Conditional operator can evaluate a condition applied to one or more expressions. The result of the evaluation is either true or false. The records are included in the response based on the evaluation result. The conditional operators will work on any numeric and/or date fields.

The Greater than (gt) operator will evaluate if the field value is greater than the provided value.

The Greater than or Equals (gte) operator will evaluate if the field value is greater than or equal to the provided value.

The Less than (lt) operator will evaluate if the field value is less than the provided value.

The Less than or Equals (lte) operator will evaluate if the field value is less than or equal to the provided value.

The Between (bt) operator will evaluate whether the field value lies between the two provided values.

Date Operators:

The Date operators allow a Consumer to work with Date and DateTime fields. The date operations are a combination of Conditional or specific Date operators (gl, gle, lt, lte, bt, within) combined with convenience keywords to particular dates and date range such as “today”, “now”, “nextWeek”, “currentYear”, “previousQuarter”.

A Consumer can also use a specific date value instead of keywords. Combinations can be applied by utilising these operators and keywords to achieve the desired results.

The following conditional operators are used for Date operations - Between (bt), Greater than (gt), Greater than or Equals (gte), Less than (lt), and Less than or Equals (let). These operators are supplemented by the Within operator and the keywords:

("now", "today", "tomorrow", "yesterday", "currentMinute", "currentHour", "currentWeek", 
"currentMonth", "currentQuarter", "currentYear", "nextMinute", "nextHour", nextWeek", 
"nextMonth", "nextQuarter", "nextYear", "previousMinute", "previousHour", "previousWeek", 
"previousMonth", "previousQuarter" and "previousYear").

Query Parameters result

Within the API Explorer, these query operators can be applied as per the requirement, and that will provide the right combination for the query parameter. This feature is user-friendly, allowing users to explore and learn quickly.