Foglight for Virtualization Enterprise Edition 8.9.3 - REST API Reference Guide


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

Rule — Get rule by id

•

API Name: Get rule by ID

•

Description: Filter out rules by a rule ID.

•

•

API path: /api/v1/rule/ruleId

•

Sample usage: http://<server>:<port>/api/v1/rule/ruleId

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Script — Publish custom REST API


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown

Script

•

Script — Run Script

•

•

Script — Run named scripts

Script — Run Script

•

API Name: Run Script

•

Description: You need be granted both the Administrator and API Access roles to use this API. This API is similar to the script console, but it does not support functionHelper, log, and out variables that are supported in the script console.


Name	Description
script	The script content.
catridgeName	Specifies the name of associated cartridge, and the name is case-sensitive.
scopeObjectId	Specifies the scope object. This item must be set if the scope variable is being used in scripts.

This API is disabled by default after the installation. Refer to the REST_DisabledAPI Registry Variable in Table 2 for more information about how to change this configuration.

•

•

API path: /api/v1/script/runScript

•

Generate a post request using the following URL: http://<server>:<port>/api/v1/script/runScript


	NOTE: If you use & in your sample codes, make sure to convert it to &.

The basic format of request body can be set as below:

{"script":"System.err.println('Hello World!')"}

The complete format is as below:

</ScriptBean>

{"script":"#utilization#", "scopeObjectId":"3ebb2158-e5e9-4403-be3c-46fd8020efeb", "cartridgeName":"Infrastructure"}

<cartridgeName>Infrastructure</cartridgeName>

</ScriptBean>

•

Data format = JSON, this value is application/json”.


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json

•

•

•

Data format = XML, this value is “application/xml”.

•

Script — Publish custom REST API


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Publish custom REST API

•

Description: The Management Server provides the capability for publishing custom REST API with scripts. To run scripts of custom REST API, ensure that the value of Choose an Associated Cartridge (Optional) is set to Forge-RestAPI in the Administration > Tooling > Script Console > Scripts > Add > Run Script dialog box. This API is a runtime registration, so the registered custom REST APIs will be lost after restarting the server.

•

Request type: Depends on the API definition.

•

API path: Depends on the API definition.

•

Sample usage: See below for the template about how to publish a custom REST API.

/*Hint: disable @variable usage, use server.context('variable') instead*/

import javax.ws.rs.*;

import javax.ws.rs.core.*;

import javax.ws.rs.container.*;

import javax.servlet.http.*;

import com.quest.forge.rest.annotation.Secured;

import com.quest.forge.rest.service.*;

import com.quest.forge.rest.api.*;

@Path("/echo")

@Secured

@Produces("application/json")

class MyResource{

@Context

private ContainerRequestContext requestContext;

@Context

protected HttpServletRequest request;

@GET

@Path("host")

public Response echoSampleHost(){

def foglightServiceLocator = ServiceFactory.getInstance().getFoglightServiceLocator();

def ts = foglightServiceLocator.getTopologyService();

def hosts = ts.getObjectsOfType(ts.getType("Host"));

if(!hosts){

return Response.ok("Empty hosts").build();

}else{

def host = (hosts as List).get(0);

def helper = foglightServiceLocator.getExtensionContext().get(ForgeRestApiHelper.class);

def entity = null;

try{

entity = helper.toSerializableEntity(host, request, requestContext);

}catch(ConversionException e){

entity = host.toString();

return Response.ok(entity).build();

class MyRestAPIExtension implements ForgeRestApiExtension{

@Override

public Class getRestResourceClz(){

return MyResource.class;

public String getCartridgeName(){

@Override

return "DummyCartridge";

def rrm = server.context('extensionContext').get(RestResourceManager.class);

rrm.registerRestAPIExtension(new MyRestAPIExtension());

After running the above codes in the Script Console dashboard, you can access this API with the http://<fms_ip>:<fms_port>/api/v1/echo/host URL.

Note the following:

•

Use rrm.registerRestAPIExtension (replaces MyRestAPIExtension()) to register the custom API.

•

Use rrm.unregisterRestAPIExtensions (DummyCartridge) to remove the custom API.

•

The @Path annotation is used to define the relative URI path.

•

The @Get annotation is used to define the request type.

•

The @Produces annotation is used to define the MIME media types of representations a resource can produce and send back to the client.

•

The @Secured annotation is used to define whether the access token is required. If @Secured is used, Access-Token must be set in the request header.

For more information about annotations, visit JAX-RS Application, Resources and Sub-Resources.

•

Header: Depends on the API definition.

•

Script — Run named scripts


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Run named scripts

•

Description: Foglight supports embedding named scripts into cartridges by editing the monitoring policy XML. This API is used to call those named scripts.

•

•

API path: /api/v1/script/runNamedScript?scriptName=<namedScriptName>&param=<script_parameter>

•

Sample usage: Consider for example there is a named script called 'getHostById', this named script requires the host instance id which type is string, then the sample API should be following: http://sever_url:port/api/v1/script/runNamedScript?scriptName=getHostById&param=b1b3ad72-2460-4576-b1ec-3ffd57016deb.

•

Header:


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.

•

Parameter:


Field	Type	Description
param	String	This value is optional and depends whether the naming script has parameter. Separate multiple parameters by commas.

•

The Subscribe related APIs include the following:


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

Subscribe alarm

•

Subscribe alarm — Disconnect SSE

•

Subscribe alarm — List SSE

•

Subscribe alarm — Subscribe alarms by object ID

•

Subscribe alarm — Subscribe all alarms

Subscribe alarm — Disconnect SSE

•

API Name: Disconnect SSE

•

Description: Disconnect all the active Server-Sent Events (SSE) subscriptions.

•

•

API path: /api/v1/subscription/disconnect/all/

•

Sample usage: http://<server>:<port>/api/v1/subscription/disconnect/all/

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Subscribe alarm — List SSE


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: List SSE

•

Description: Filter out all the active SSE subscriptions.

•

•

API path: /api/v1/subscription/list/

•

Sample usage: http://<server>:<port>/api/v1/subscription/list

•


Field	Type	Description
Access-Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Subscribe alarm — Subscribe alarms by object ID


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Subscribe alarms by object ID

•

Description: Watch the topology object by its topologyId, and subscribe to alarm-generated events through SSE. When the client is disconnected, there is no retry mechanism to send an event to the client. For more information, visit Server-Sent Events (SSE) Support and Server-Sent Events.


	NOTE: If the version of your Foglight Management Server is lower than 5.7.5.7, open the server.xml file under <fms_home>/server/tomcat/, then add asyncSupported="true" to all value items (for example, <Valve className="com.quest.nitro.web.tomcat.HttpsRedirectValve" asyncSupported="true"/>).

•

•

API path: /api/v1/subscription/alarm/subscribe/topologyId

•

if(typeof(EventSource) !== "undefined")

{var source = new EventSource("http://<server>:<port>/api/v1/subscription/alarm/subscribe

/67beea68-fa6f-4cd3-b122-dcb20db50360?Accept=application/json&Access-Token=sanpqvi54h9a59n03u6illuahj", {withCredentials: true});source.onmessage = function(event)

document.getElementById("result").innerHTML += event.data + "<br>";

};

} else {

document.getElementById("result").innerHTML = "Sorry, your browser does not support server-sent events...";

</script>

•

Subscribe alarm — Subscribe all alarms


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Subscribe to all alarms

•

Description: Subscribe to alarm-generated events through SSE. When the client is disconnected, there is no retry mechanism to send an event to the client. For more information, visit Server-Sent Events (SSE) Support and Server-Sent Events.


	NOTE: If the version of your Foglight Management Server is lower than 5.7.5.7, open the server.xml file under <fms_home>/server/tomcat/, then add asyncSupported="true" to all value items (for example, <Valve className="com.quest.nitro.web.tomcat.HttpsRedirectValve" asyncSupported="true"/>).

•

•

API path: /api/v1/subscription/alarm/subscribe

•

if(typeof(EventSource) !== "undefined") {

var source = new EventSource("http://<server>:<port>/api/v1/subscription/alarm/subscribe?Accept=appl ication/json&Access-Token=5vr9jmptoskrpheaj2e31vvna6", {withCredentials: true});

source.onmessage = function(event) {

document.getElementById("result").innerHTML += event.data + "<br>";

};

} else {

document.getElementById("result").innerHTML = "Sorry, your browser does not support server-sent events...";

</script>

•

Topology — Get properties’ value


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

Topology

•

•

Topology — Get property value

•

Topology — Get topology object by id

•

Topology — Get topology object by ids

•

Topology — Observations query

•

Topology — TopologyObject query

•

Topology — Push data

Topology — Get properties’ value

•

API Name: Get properties’ value

•

Description: Get properties of one topology object based on path. This topology object is specified by uniqueId.

•

•

API path: /api/v1/topology/topologyId/paths

•

Sample usage: http://<server>:<port>/api/v1/topology/3546fa55-11b6-4943-b7cb-84ddcf350bc5/paths?path=name&path=uniqueId&path=utilization

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Parameter:


Field	Type	Description
path	String	The property path. This may include multiple paths.

•

Topology — Get property value


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Get property value

•

Description: Get property values by the path defined based on the given topology ID. The result may be DataObject, Primitive Object, Observation, or else.

•

•

API path: /api/v1/topology/topologyId/path

•

Sample usage: http://<server>:<port>/api/v1/topology/abc94b3d-f599-4766-a979-f32d372ff47d/cpus/utilization

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Topology — Get topology object by id


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Get topology object by IDs

•

Description: Filter out topology objects by an object ID.

•

•

API path: /api/v1/topology/topologyObjectId

•

Sample usage: http://<server>:<port>/api/v1/topology/1f478dec-f920-4da9-a8d2-b9ba0dcd4394

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Topology — Get topology object by ids


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Get topology object by ids

•

Description: Filter out topology objects by multiple IDs.

•

•

API path: /api/v1/topology/topologyIds

•

Sample usage: http://<server>:<port>/api/v1/topology/topologyIds?Id=3546fa55-11b6-4943-b7cb-84ddcf350bc5&Id=67beea68-fa6f-4cd3-b122-dcb20db50360

•


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

Parameter:


Field	Type	Description
Id	String	The topology object ID. This may include multiple IDs.

•

Topology — Observations query


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: Observations query

•

Description: Filter out observations value by a batch query. The following lists the retrievalType:


Name	Description
RAW	Retrieve the raw data of an observation based on the time range.
AGGREGATE	Retrieve the aggregate data of an observation based on the time range.
AGGREGATE_AND_LAST	Retrieve the aggregate and last data of an observation based on the time range.
LAST_N	Retrieve the last N data of the observation based on the time range. If retrievalType is set to LAST_N, you need configure the value of numberOfValue that defines the letter N of LAST_N.

•

•

API path: /api/v1/topology/batchQuery

•

Generate a post request using the following url:

"http://<server>:<port>/api/v1/topology/batchQuery"

The basic format of request body can be set as below:

{"includes":[{"ids":["ca83d1a2-f04b-483d-b224-055967777e72"],"observationName":"utilization"}],

"endTime":1477987660722}

The following is the complete format of request body:

"includes":[{"ids":["ca83d1a2-f04b-483d-b224-055967777e72"],"observationName":"utilization"},

{"ids":["f58f36ef-88ef-4264-9b8a-91df79fd37e9"],

"observationName":"utilization"},

{"ids":["f3df86e1-0718-4ccf-ae05-c25414b53db9",

"7910afd1-0247-4309-bae4-05f9419ab719",

"4ed2b409-cf18-4c14-a6ab-fdc19cff006e"],

"observationName":"percentMemory"}],

"startTime":1477984060722,

"endTime":1477987660722,

"granularity":3600000,

"numberOfValue":1,

"retrievalType":"AGGREGATE_AND_LAST"

<observationName>utilization</observationName>

</includes>

<observationName>utilization</observationName>

</includes>

<observationName>percentMemory</observationName>

</includes>

<retrievalType>AGGREGATE_AND_LAST</retrievalType>

</observationQueryParamBean>

•

Data format = JSON, this value is “application/json”.


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

•

•

Data format = XML, this value is “application/xml”.

•

Topology — TopologyObject query


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

API Name: TopologyObject query

•

Description: Filter out topology objects by a batch query.

•

•

API path: /api/v1/topology/query

•

Generate a post request using the following url:

http://<server>:<port>/api/v1/topology/query

The basic format of request body can be set as below:

{"queryText":"!Host"}

The following is the complete format of request body:

"freshnessFactor":3600000.0,

"queryText":"!Host",

"caseSensitive":true,

"params":[{"name":"name","value":"nameofHost"},

{"name":"domainName" ,"value":"nameofDomain"}],

"queryTopologyObjects":true,

"requiresCoherentResults":true,

"scopingTopologyObjectId":"4f888425-a734-4bee-a5a7-4e24cd3c83cd",

"transactionTimestampMillis":3600000,

"ti meRangeStartTime":1477984060722,

"timeRangeEndTime":1477987094482,

"timeRangeGranularity":3600000,

"timeRangeMaxPoints":500

<value>nameofHost</value>

</params>

<name>domainName</name>

<value>nameofDomain</value>

</params>

</queryParamBean>

•

Data format = JSON, this value is “application/json”.


Field	Type	Description
Access- Token	String	The token is retrieved after successfully logging in to the Management Server.
Accept	String	Specifies the response data format which can be either application/json or application/xml. The default value is application/json.

•

•

•

Data format = XML, this value is “application/xml”.

•


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

Topology — Push data

•

API Name: Push data

•

Description: Push data to an existing topology object. The request body should be RAW data and the basic format can be set as below:

"simplePropertyName": "TestData1",

"data":[{

"typeName": "TypeName",

"properties": {

"MetricPropertyName": 11234,

"ObservationPropertyName": {

"simplePropertyNameOne": "testObservation1",

"simplePropertyNameTwo": 1495447993592,

"simplePropertyNameThree": 1495447993592

When invoking this API, note the following:


Name	Description
data	Mandatory. Specifies the detailed data of an object.
typeName	Mandatory. Specifies the data type, and this field must be either of TopologyObject or its sub type.
properties	Mandatory. Specifies the property value of the type.
startTime	Mandatory. Specifies the data start time.
endTime	Mandatory. Specifies the data end time.
agentName	Mandatory. Specifies the value (in the string format) which identifies the client running this API.

•

Ensure that the data type (typeName) already exists in the server; otherwise this operation will fail.

If the data type is a new type, import this type by selecting Dashboards > Administrator > Data > Add Topology Type. Click the Help tab in the Add Topology Type dashboard to understand details of this new type.

•

All topology objects have the identity property (properties). The Management Server, based on this identity property, decides to merge the object with an existing object or to create a new object.

To find the identity property of a type, select Dashboards > Development Tools > Schema Browser (ensure that you have the Cartridge Developer role). If the identity property is a topology object, you can use the object unique ID as its reference. Fore more information, refer to the following Sample usage section.

The identity of Host type (hostId) is generate by some fields, so set the name and hostId properties at least if you want to create a host.

•

For the Observation type (including Metric) data, the data start time and end time use startTime and endTime in the request body.

•

If you see the message like “The rest agent cache queue is full...” in the log file, increase the value of the REST_AgentSubmitInfoQueueSize Registry Variable, and then run the following script in the Run Script dialog box. To run the following script, ensure that the value of Choose an Associated Cartridge (Optional) is set to Forge-RestAPI in the Administration > Tooling > Script Console > Scripts > Add > Run Script dialog box.

import com.quest.forge.rest.service.impl.RestAgentManagerImpl;

RestAgentManagerImpl.updateConfig();

•

•

API path: /api/v1/topology/pushData

•


Field	Type	Description
Access-Token	String	The token is retrieved after successfully logging in to the Management Server.
Content-Type	String	Data format = JSON, this value is “application/json”.

•


Field	Type	Description
status	String	The response status.
data	String	Either the response data format (JSON/XML) or exception message.
error	String	Error code if some exception occurs; otherwise this field is not shown.

•

•

Case 1: Create a general topology type instance. Consider for example we create an FSMAgentBlackout type instance. Find the identity of type FSMAgentBlackout is name in the Schema Browser dashboard. Use the following request body to create the FSMAgentBlackout type instance.

"typeName": "FSMAgentBlackout",

"data":[{

"properties": {

"name" : "Test-FSMAgentBlackout"

•

Case 2: Create a Host instance. If you want to submit Host type data, the name property is mandatory while vmId and systemId properites are optional. You can set both optional properties if you know their values. hostId is automatically generated based upon values of name, systemId, and vmId, so it is not required to set manually.

"hostId" : "Test-Host",

"name" : "Test-Host"

•

Case 3: Create a type instance which identity property is a topology object. Consider for example we create a HostProcess type instance. In the Schema Browser dashboard, find the identity properties of type HostProcess are name and os. The name property is a string, while the os property is OperatingSystem which is a topology type. Use the uniqueId of OperatingSystem as the reference, then create the HostProcess type instance as follows.

"os" : "e197ee1a-a60d-4627-8313-72d6bd49ce61",

"data":[{

"name": "HostProcess",

"properties": {

"name" : "Test-HostProcess"