Listing entities

Retrieve information about existing entities in a Decision Server Insights solution project by using the GET operation that is provided by the REST API.

About this task

You can retrieve information about existing solution entities by sending a GET operation request to the Insight Server. Depending on how you construct the GET request, the returned list includes information about all installed solutions, all entities that are associated with a specific solution, or a single entity that is identified by a key value.

Procedure

Make sure you can access the Insight Server by entering the generic REST URL in the browser address field. See Managing entities for an example of the REST URL.

Using your browser, or a script, send a GET request to retrieve information about solutions and entities. Examples of the GET request syntax are provided in the following table.

Depending on the value of the httpEndpoint setting in the server.xml file on your system, the first part of the request URL is http://hostname:9080 for httpPort connections, or https://hostname:9443 for httpsPort connections.

Table 1. GET request syntax
Type of information requested	Request syntax	Optional parameters
All installed solutions	`.../ibm/ia/rest/solutions`
All entities that are associated with a specific solution	`.../ibm/ia/rest/solutions/solution_name/entity-types/entity_type/entities`	group, max
An entity with a specific value, such as ID	`.../ibm/ia/rest/solutions/solution_name/entity-types/entity_type/entities/entity_id`	group, max, regex

Include the following optional parameters in GET requests to control the display of the response, or retrieve an entity that includes a key value such as an ID:

group

Groups the list of entities into pages if the returned list is too long to read easily. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/CustomerID?group=1

where the number of CustomerID entities in the response is limited to a one-page list.

max

Limits the number of items that are included in the returned list of entities. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Transactions/entities?max=10

where the value of the max parameter allows 10 transactions in the entities list.

Tip: The default number of items in a list of entities is 50. You can increase the number of entities included in the list by specifying a max parameter with a value greater than 50.

max&group

Combines the max and the group parameters to organize the list of entities. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Transactions/entities?max=100&group=2

regex

Retrieves an entity, or a set of entities, that match a regular expression (regex). Add the regular expression query string to the GET request. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/CustomerID?regex=20[0-5]

where 20[0-5] is a regular expression and only entities with IDs that match the criteria defined by the expression, including 200, 201, 202, 203, 204 and 205, are returned in the server response.

Add the asterisk wildcard character to the regex parameter to match an expression pattern. For example, you can retrieve all entities that have a name starting with the letter f.

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/CustomerID?regex=f.*

Optional: Include the If-None-Match ETag header in the request to retrieve only entities that changed since the previous request.
Tip: If you make frequent GET requests, or a large number of entities is returned by your GET requests, the volume of requests might affect event processing performance. Use the ETag header to optimize entity retrieval and improve processing speed.