Topology Object Query through REST APIs

The query of topology objects is one of the functionalities provided by Foglight REST APIs. The following samples demonstrate how to query topology objects and customize the query criteria using request parameters. For more information about REST APIs, please refer to Foglight REST APIs.

• Topology object query by topology ID
• Topology object query by property name
• Customization of topology object query
  
  • Limited number and depth of result objects
  • Limited properties of result objects

Topology object query by topology ID

If you already know the unique ID of a topology object, you can search for this topology object using the "Get topology object by ID" REST API. The following is the API description that can be found at:

http://{{serverurl}}:{{serverport}}/api/doc/#api-Topology-GetApiV1TopologyTopologyobjectid.

The following is a sample response when searching for a host topology object which unique ID is known to user.

Topology object query by property name

If you want to search for topology objects based on their properties, perform the topology query using the "Topology object Query" REST API. The following is the API description that can be found at:

http://{{serverurl}}:{{serverport}}/api/doc/#api-Topology-PostApiV1TopologyQuery

For example, if you want to query a host topology object which name is "zhuvmwerp2571", invoke the "Topology object Query" REST API and set the request body as below:

{"queryText":"!Host where name=:name","params":[{"name":"name","value":"zhuvmwerp2571"}]}

The following is an example of query response.

To find all properties of a topology object, then you can perform the topology object query more efficiently. To find all properties of a topology object, do the following:

1. Check and make sure you have been granted with the "Cartridge Developer" role.
2. On the navigation panel, under Dashboards, click Development Tools > Schema Browser.
3. In the Schema Browser page, browse to select a topology object.

The following shows the properties of the Host topology object.

Customization of topology object query

The following table shows the list of registry variables that can be used to customize the topology object query.

The following table shows the list of parameters that are used for URL requests. The value of some URL parameters is overridden by the value of registry variables listed above. For example, the default value of "MaxDepth" is 1, which means the value of "REST_MaxDepth" registry variable is 1. For more details, you can refer to the REST API doc at http://serverapi:serverport/api/doc/#api-Overview.

The following introduces two examples of customized queries.

Limited number and depth of result objects

We don't recommend querying all objects, especially for a large-scale environment. We have limited the serialization output to 500 objects (including the contained objects) by default.
If you want to request the Host topology objects with a limited number of results and limited max depth, we offer the following two options:

• Modify the value of the "REST_MaxObjectCount" (e.g. REST_MaxObjectCount=3) and "REST_MaxDepth" (e.g. REST_MaxDepth=0) registry variables

• Add "maxObjectCount" and "maxDepth" as parameters of your request: http://{{serverURL}}:{{serverPort}}/api/v1/type/Host/instances?maxObjectCount=3&maxDepth=0

The following shows the sample response of this customized query.

Limited properties of result objects

You can add "includePropertyPatterns" and "excludePropertyPatterns" as parameters of your request to limit the properties of result objects. Both parameters support regular expression. If conflict occurs, the "excludePropertyPatterns" parameter will be ignored.
The following sample query excludes objects with the "aggregated." or "Aggregated." pattern, but includes objects with the "aggregateState" pattern. "showTopologyTypeLocalProperties=true" means the properties of result topology object will be shown together with the result objects.

http://{{serverURL}}:{{serverPort}}/api/v1/type/Host/instances?excludePropertyPatterns=.*aggregate.*, .*Aggregate.*&&includePropertyPatterns=aggregateState&showTopologyTypeLocalProperties=true