REST API queries

You can use the REST API in connection with the Query Language. For a reference of Query Language operators and commands, see REST API collection query protocol.

Retrieving related record properties

The EMS enables you to query for properties defined on related records.

Example: Consider the following pseudo meta-model:

Entity:Incident {
	Property: Id
	Property: Name
	Property: Owner->IncidentOwner
}

Entity:User {
	Property: Id
	Property: Name
	Property: Email
}

Relationship:IncidentOwner {
	From: Incident
	To: User
}

and the following REST call:

where tenant-id represents the tenant ID. To access the tenant ID, right-click the Launch button next to the required product on MyAccount, select Copy link address and paste it into a browser. The tenant ID is the number following TENANTID=.

The following result is returned:

{
       	"entities": [
       			{
                      		"entity_type": "Incident",
                              "properties": {
					"Id": "12226789",
                                     	"Status": "Open",
					"Owner": "123651234"
					
},
"related_properties" : {
					"Owner": {
						"Name": "Jimi",
						"Email": "jimi@microfocus.com"
					}

}

                       }
],
"meta": {
"completion_status": "OK",
	}

}

Retrieving related records

This section refers to the EMS query API for querying entities based on relationships and paths to another record type.

The EMS supports a generic API for retrieving entities based on relationships or paths and a specific record ID. This API supports all relationship types (one-to-many, many-to-many, and one-to-one) in both directions.

Example 1 (changes caused by incident): Return all the changes caused by the Incident with Id=<id> via the ChangeCausedByIncident relationship. Enter the following request URI:

Example 2 (incidents caused by change): Return all the Incidents caused by changes with Id=<id> via the IncidentCausedByChange relationship. Enter the following request URI:

Retrieving grouped aggregated record data

The EMS supports basic, generic grouping and aggregation of record data, based on the meta-model, similar to the row-data APIs. This API supports basic aggregation functions on filtered record data, using the same filtering semantics specified for the row-data APIs.

Supported functions

The EMS supports the following aggregation functions:

• count
• sum
• avg
• min
• max

Supported Query Parameters

The EMS API supports the grouping of aggregated results, similar to the SQL GROUP BY feature and with the same semantics.

Example: Return the sum of all incidents grouped by priority category ID and category display label. Enter the following request URI:

where tenant-id represents the tenant ID. To access the tenant ID, right-click the Launch button next to the required product on MyAccount, select Copy link address and paste it into a browser. The tenant ID is the number following TENANTID=.

The full request is as follows:

The response body appears as follows:

{
    "Results": [
        {
            "Properties": {
                "Priority": "HighPriority"
            },
            "RelatedProperties": {
                "Category": {
                    "DisplayLabel": "Hardware",
                    "Id": "10667"
                }
            },
            "Aggregations": {
                "Count": {
                    "Id": 2
                }
            }
        },
        {
            "Properties": {
                "Priority": "CriticalPriority"
            },
            "RelatedProperties": {
                "Category": {
                    "DisplayLabel": "Desktop Support",
                    "Id": "10707"
                }
            },
            "Aggregations": {
                "Count": {
                    "Id": 1
                }
            }
        },
        {
            "Properties": {
                "Priority": "LowPriority"
            },
            "RelatedProperties": {
                "Category": {
                    "DisplayLabel": null,
                    "Id": null
                }
            },
            "Aggregations": {
                "Count": {
                    "Id": 16
                }
            }
        },
        {
            "Properties": {
                "Priority": "LowPriority"
            },
            "RelatedProperties": {
                "Category": {
                    "DisplayLabel": "Access (Accounts & Passwords)",
                    "Id": "10663"
                }
            },
            "Aggregations": {
                "Count": {
                    "Id": 5
                }
            }
        }
    ],
    "meta": {
        "completion_status": "OK",
        "errorDetails": null,
        "total_count": null,
        "correlation_id": null
    }
}

Filtering based on related record properties

The EMS supports filtering based on related record properties.

• Filtering based on many-to-one record properties

  Conditions on related record properties can be built using the DOT notation, similar to the approach specified in Retrieving related record properties.

  Example: Return the Id and Summary of all Incidents that are owned by a user named Jimi. Assuming Owner is a reference property of a user. Enter the following request URI:

  HTTP GET: rest/<tenant-id>/ems/Incident?layout=Id,Summary&filter=Owner.Name=’Jimi’

• Filtering based on many-to-many record properties – vector conditions

  The EMS query language supports filtering based on related record properties, typically using a relationship name, but also using paths, as defined in the metadata. Relationships of all types are supported (one-to-many, many-to-many, and one-to-one).

  A filter condition on related records can be combined with conditions on the queried records using logical conditions.

  The following syntax is supported:

  notexists? IDENTIFIER [condition?]

  where:

  notexists represents an operator which evaluates to true when the following vector condition is empty.

  IDENTIFIER represents a relationship or path name.

  condition represents a filter that filters the vector according to a condition based on the properties of the related record.

  Example 1 (inclusive): Return the Ids of all articles that have been read by all users named Jimi. Enter the following request URI:

  HTTP GET: rest/<tenant-id>/ems/Article?layout=Id&filter=ArticlesToReaders[Name=’Jimi’]

  Example 2 (exclusive): Return the Ids of all articles that have not been read by any user named Jimi. Enter the following request URI:

  HTTP GET: rest/<tenant-id>/ems/Article?layout=Id&filter=notexists ArticlesToReaders[Name=’Jimi’]

Query Language extensions

For a reference of Query Language operators and commands, see REST API collection query protocol.

• Wild-card string matching conditions

  The EMS REST query protocol supports the starts with condition for properties of type string with the following syntax:

  IDENTIFIER startswith(STRING_LITERAL)

  or

  IDENTIFIER sw(STRING_LITERAL)

  where:

  STRING_LITERAL represents a string literal wrapped with single quotes. Note that if a single quote character is a part of the string literal itself, an additional single quote character must be added. Example: The string Jimi’s new guitar should be passed as Jimi’’s new guitar.

  Example: Return the Ids of all people whose first names start with Sh. Enter the following request URI:

  HTTP GET: rest/<tenant-id>/ems/Person?layout=Id&filter=FirstName startswith(’Sh’)

• Unassigned/Null property conditions

  The EMS REST query protocol supports null expressions in conditions. As in many programing languages, null expressions represent unassigned or empty values.

  The following syntax is supported:

  IDENTIFIER = null

  where:

  IDENTIFIER represents a record property name.

  Example: Return the Ids of all people whose owner is not set to a value. Enter the following request URI:

  HTTP GET: rest/<tenant-id>/ems/Person?layout=Id&filter=Owner = null

• Restrictions and limitations

  Beyond the standard query language, the EMS has some limitations and restrictions regarding the usage of its APIs:

  • Low Selectivity Filter Conditions. For performance reasons, the EMS may be unable to process record queries that contain low selectivity filters. Low selectivity filters are filters that contain no inclusive conditions.

    Low selectivity filter conditions include:

    • notexists type vector conditions
    • Not equals (!= or ne) conditions
    • Null comparison condition (X = null)

  • Ordered Query Total Size Limit. Queries that specify order are limited to 4,000 records in total size. If an ordered collection query returns more than 4,000 records, the service returns an error.

  • Query size parameter. All collections must include a size restriction. If the size query parameter is not specified, it is automatically set to 100, meaning that no more than 100 records are returned.

  • Query layout parameter. The query layout parameter is required in all GET operations and does not support wildcards. You must explicitly request any property which you expect the service to return.

  • Properties returned In collections. Properties of type text and complex-type cannot be retrieved within a collection. To retrieve such properties, you must issue a single record request. This limitation is designed to prevent extreme page sizes that can cause performance problems, both for network bandwidth and memory consumption reasons.

Related topics

• Overview of the REST API

• How to connect to the REST API

• Authentication endpoint service

• Single record API

• Record bulk update and collection APIs

• REST API collection query protocol

• Analytics REST API

• REST API use case scenario - import REST API