Search and Include
Search Criteria
Data returned from an API
call can be filtered to a specific subset before being returned based
on a search string passed to the API in the request body using the searchCriteria request parameter. A filter is applied
as filterName(fieldname,comparisonValue)
where the
comparison value is applicable based on the filter being used.
Syntax: filterName(fieldname,comparisonValue)
For example, searchCriteria: "where equals(menuItems.active,Y)"
returns the active menu item records.
Using Multiple Search Criteria
Multiple
search criteria can be strung together using AND
and OR
logical operators and grouped by using parentheses when
nesting search criteria.
Syntax: filterName(fieldname,comparisonValue)
<Logical Operator> filterName(fieldname,comparisonValue)
For example, searchCriteria: "equals(active,1)"
limits the response to only contain rows where the top level field active
has a value of 1. The statement searchCriteria:
"(equals(active,1) and equals(type,1))"
further limits the
response to only rows that were both active and of type 1.
Negating the Filter Condition
Use the symbol !
to apply a value of NOT
to any filter
that reverses the filter condition.
Syntax: !(filterName(fieldname,comparisonValue))
For example, the statement searchCriteria: "!(equals(active,1))"
further limits the response to the rows that are not active.
Available Search Criteria Filters
Consider the following example from a guest check API response:
{ "curUTC": "2019-07-20T17:59:59", "locRef": "1234", "guestChecks":[{ "guestCheckId":124563, "chkNum": 7, "chkName": "Check Name", "opnBusDt": "2019-07-20", "opnUTC": "2019-07-20T15:20:20", "clsdBusDt": "2019-07-20", "clsdUTC": "2019-07-20T16:16:10", "reopnClsdChkClsdBusDt":"2019-07-20", "reopnClsdChkClsdUTC":"2019-07-20T16:16:10", "lastUpdatedUTC": "2019-07-20T16:16:10", "clsdFlag": true, "gstCnt": 2, "subTtl": 123.50, "autoSvcTtl": 0.00, "svcChgTtl": 2.50, "nonTxblSlsTtl":1.25, "txblSlsTtl":22.00, "taxExmpSlsTtl":1.75, "taxCollTtl": 1.45, "chkTtl": 25.00, "dscTtl": 3.00, "payTtl": 0.00, "balDueTtl": 0.00, "reopenFrmChk": 1, "reopenToChk": 1, "spltFrmChk": 1, "rvcNum": 123, "otNum": 12, "tblNum": 123, "tblName": "123", "empNum": 21334, "chkInfo": "Manually Entered Text", "taxes":[{ "taxNum":123, "txblSlsTtl":12.34, "taxCollTtl":1.34, }] ..... ..... }] }
You can use the following filters to filter the response in the API request:
Filter Name | Filter Description | Supported Data Type | Parameter 1 | Parameter 2 | Example |
---|---|---|---|---|---|
equals |
Searches for records where the specified column's value is exactly equal to the comparison value |
All |
Column name |
Comparison value |
|
equalsIgnoreCase |
Searches for records where the specified column's value is equal to the comparison value without considering the string value's case |
String |
Column name |
Comparison value |
|
greaterThan |
Searches for records where the specified column's value is greater than the comparison value |
Any numeric type |
Column name |
Comparison value |
|
lessThan |
Searches for records where the specified column's value is less than the comparison value |
Any numeric type |
Column name |
Comparison value |
|
isNull |
Searches for records where the specified column's value
is equal to |
All |
Column name |
N/A |
|
contains |
Searches for records where the specified column's value contains the comparison value |
String |
Column name |
Comparison value |
|
startsWith |
Searches for records where the specified column's value starts with the comparison value |
String |
Column name |
Comparison value |
|
endsWith |
Searches for records where specified column's value ends with the comparison value |
String |
Column name |
Comparison value |
|
Search Criteria Considerations
-
The type of data applied for
"comparisionValue"
must be of the same as the underlying type of"fieldName"
. -
Enclose strings in single quotes when using
"comparisonValue"
. -
Nested objects must be indicated by prepending the parent object name(s) to the field.
For example, for the following structure, the response returned inside the revenue centers listed may be limited based on Service Charge Number 12345 by passing
"searchCriteria: equals(revenueCenters.serviceCharges.svcNum,12345)"
in the API request body.{ "locRef":"1234", "busDt: "2020-07-20", "revenueCenters":[{ "rvcNum": 1372, "serviceCharges":[{ "svcNum": 12345, "ttl": 1234.56, "cnt": 123 }] }
Include
All the Oracle MICROS REST APIs
return a set of default attributes as part of the response. There
could also be some default attributes which might not be returned
in the response in case their value is Null, 0, or False. Please refer
the detailed API documentation for understanding the attributes in
the response. The optional attributes can be retrieved using the include
request parameter.
Use the include
request parameters to retrieve a specific attribute from the API
response. Using the include parameter will override the default behavior
of the attributes in the response and will return only the response
attributes mentioned in the request.
Syntax: include: "fieldName1, fieldName2....fieldNameN"
For
example, using include: "locRef, busDt, revenueCenters.num,
revenuCenters.name"
returns the revenue center name and revenue
center number from the getRevenueCenterDimensions
API instead of the entire response.
{ "locRef":"1234", "busDt: "2020-07-20", "revenueCenters":[{ "num": 152, "name": "Bar" }] }
Note:
Use the parent object's name with the object name when using theinclude
request parameter.