REST API collection query protocol
This section provides specifications for HTTP GET query parameters designed to be used with REST services APIs.
Collection filtering
The filter query parameter specifies a filtering condition for a resource collection. The service then returns only resources that meet the specified condition.
Logical operators
The following logical operators are supported:
| Name | Description | Examples |
|---|---|---|
| Logical And | Evaluates to true if both the left and right operands evaluate to true, otherwise evaluates to false. |
|
| Logical Or | Evaluates to true if at least one of the left and right operands evaluates to true, otherwise evaluates to false. |
|
Note Logical Not is not supported. Specific operators have their own negation syntax. For example: “in” and “not in”, “=” and “!=”.
Comparison operators
Comparison logical operators evaluate to a boolean value depending on the operand values.
The following comparison operators are supported:
| Name | Description | Examples |
|---|---|---|
| Equals | Evaluates to true if the left and right operands are equal, otherwise evaluates to false. |
|
| Not equals | Evaluates to true if the left and right operands are not equal, otherwise evaluates to false. |
|
| Greater than | Evaluates to true if the left operand is greater than the right operand, otherwise evaluates to false. |
|
| Greater or equal | Evaluates to true if the left operand is greater than or equal to the right operand, otherwise evaluates to false. |
|
| Less than | Evaluates to true if the left operand is less than the right operand, otherwise evaluates to false. |
|
| Less or equal | Evaluates to true if the left operand is less than or equal to the right operand, otherwise evaluates to false. |
|
| Between | Evaluates to true if the left-most operand is in the range defined by the two comma-separated operands in the parentheses, otherwise evaluates to false. The first operand in the parentheses represents the lower limit of the range and the second the upper limit. |
http://domain/resource?filter=LastUpdate btw(2012.01.01, 2013.01.01) |
| Not between | Evaluates to true if the left-most operand is not in the range defined by the two comma-separated operands in the parentheses, otherwise evaluates to false. The first operand in the parentheses represents the lower limit of the range and the second the upper limit. Range boundaries are inclusive. |
http://domain/resource?filter=LastUpdate not btw(2012.01.01, 2013.01.01) |
| In | Evaluates to true if the left-most operand is equal to one of the expressions in the parentheses, otherwise evaluates to false. | http://domain/resource?filter=Id in(1,2,3) |
| Not in | Evaluates to true if the left-most operand is not equal to any of the expressions in the parentheses, otherwise evaluates to false. | http://domain/resource?filter=Id not in(1, 2, 3) |
Note Different expressions and data types might not have a strict definition of how they evaluate against one another, so the definition of how operators evaluate might become service dependent.
Arithmetic operators
The following artihmetic operators are supported:
| Name | Description | Examples |
|---|---|---|
| Add | Evaluates to the result of the sum of the left operand to the right operand. |
|
| Subtract | Evaluates to the value of the left operand minus the value of the right operand. |
|
| Multiply | Evaluates to the product of the left operand and right operand values. |
|
| Modulo | Evaluates to the remainder of the division of the left operand by the right operand. |
|
| Divide | Evaluates to the value of the division of the left operand by the right operand. |
|
|
Parentheses |
Used around conditions and expressions to define priority. |
|
| Unary plus | Syntax: +number | |
| Unary minus | Syntax: -number |
Layout
The layout query parameter specifies which properties or sub-structure of a data resource should be returned by a service. Similar to SQL, this parameter provides a comma separated list of properties or multi-part properties.
-
Selecting Resource Properties. Specify the required properties according to the following syntax: http://domain/resource?layout=Id,Name,Description.
-
Selecting Related Resource Properties. Specify a relationship name and a property name according to the following syntax: http://domain/Person?layout=PrimaryAddress.City.
-
Selecting a Sub-Structure Using Multipart Properties. Resources that contain complex object structures can be queried for a sub-structure using multi-part property conventions.
Example: Query a resource named UserSetting for a Select object, which is a sub-structure of a Filter object, which is a sub-structure of a UserSetting object. Enter a request according to the following syntax: http://domain/UserSetting?layout=Settings.Filter.Select.
-
Selecting Calculated Values. The query protocol supports function and arithmetic operators.
Example 1: Query a Formula resource for the product of a property named X and a property named Y. Enter a request according to the following syntax: http://domain/Formula?layout=X mul Y.
Example 2: Query a Person resource for FirstName and LastName and return a concatenation in the format “FirstName.LastName”. Enter a request according to the following syntax: http://domain/Person?layout=Concat(FirstName, Concat(‘ ’, LastName)).
Ordering
The order query parameter specifies the order in which the returned resources are placed. Similar to SQL, this parameter contains a comma-separated list of order expressions. Each order expression specifies a property name and a sort direction.
The following syntax is supported:
order=property-name desc | asc
Size
The size parameter specifies the maximum number of resources requested to be returned.
The following syntax is supported:
size=<integer>
Example: Return the first ten people with age lower than 30 in ascending order. Enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&filter=Age<30&order=Age asc&size=10
Skip
The skip parameter specifies how many resources should be skipped by specifying the starting index of the returned result. When not specified, its default value is zero, such that the first resource returned from the data-store is the first resource returned by the queried service.
The following syntax is supported:
skip=<integer>
Example: Return people, starting from person number 51. Enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&skip=50
Paging
Paging is achieved by the combination of the skip and size parameters.
Example: Return a page of 50 people starting from the first person. Enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=0&size=50.
To return the next page (page = 2), enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=50&size=50.
To return the next page (page = 3), enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&order=Id&skip=100&size=50.
Metadata
The meta parameter allows clients to request metadata about the queried object and the request itself.
The following syntax is supported:
meta=<comma separated list of meta-data properties>
Example: Return people with age greater than 10, starting from person number 51. Include the total number of people that apply to the specified filter (totalCount) and the number of returned resources (Count). Enter the following request:
http://<domain>/Person?layout=FirstName,LastName,Email&skip=50&filter=Age>10&meta= TotalCount,Count
The following are some common metadata attributes:
| Name | HTTP Method |
Retrieved |
Description | Value Range |
|---|---|---|---|---|
| completion_status | Any |
Always (based on service specifications) |
A request completion status. |
One of:
|
| totalCount | GET | On Demand (based on service specifications) | The total number of resources that apply for the request (discards skip and size). | Integer |
The following is an example of a JSON meta structure:
{
"meta": {
"completion_status": "OK",
"total_count": "1023",
}
}
String literals
String literals can be used as expressions in query elements such as comparison condition on properties, function parameters and others. A string literal must always start and end with a single quote. If a single quote character is a part of the string itself, an additional single quote character must be added.
Example: The string Jimi’s new guitar should be passed as Jimi’’s new guitar.
Locking system – service behavior
The EMS data engine implements an optimistic locking system in order to prevent clients from accidentally overwriting each other’s data. Without appropriate validation, two clients can retrieve the same record, edit it and send it to the server for update. One of the changes is committed first and the second one overwrites the record. The optimistic locking approach checks the version or timestamp of the record when it arrives and only allows updates on it if the incoming version is not lower than the version currently stored in the database.
When a record is received for update, if it does not pass the optimistic locking version validation, the transaction fails. In such cases, the REST API returns HTTP status code 409. In case of a bulk API, the 409 status is returned in the body of the response, inside the JSON which represents the corresponding record result.
Note
- To use this locking system, the incoming record must include the LastUpdateTime property with the value assigned to it when it was retrieved from the server.
- The locking system is not relevant for the Analytics REST API.
