Chat now with support
Chat with Support

Foglight Evolve 9.0 - REST API Reference Guide

Rule

The Rule related APIs include the following:

API Name: Get all rules’ data
Description: Get data of all rules.
API path: /api/v1/rule/allRules
Sample usage: http://<server>:<port>/api/v1/rule/allRules

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.

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 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

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.

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

The Script related API includes the following:

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.

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
NOTE: If you use & in your sample codes, make sure to convert it to &amp;.

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

Content-Type

String

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.
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.
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.
Header: Depends on the API definition.

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:

Access- Token

String

The token is retrieved after successfully logging in to the Management Server.

param

String

This value is optional and depends whether the naming script has parameter. Separate multiple parameters by commas.

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

The Subscribe related APIs include the following:

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/

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.

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

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.

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

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

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

The Topology related APIs include the following:

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

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.

path

String

The property path. This may include multiple paths.

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

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.

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

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.

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

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.

Id

String

The topology object ID. This may include multiple IDs.

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:

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

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.

Content-Type

String

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

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.

Content-Type

String

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: 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:

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.
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.
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.
API path: /api/v1/topology/pushData

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”.

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.
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.
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.
Case 4: Create a custom type instance. Consider for example we have imported the below type definition in the Add Topology Type dashboard.
The identity property is name in the above type definition. Use the following request body to create the custom type instance:
Case 5: Consider for example we have the following type definition.
Case 6: Consider for example we have the following type definition.
Related Documents