Foglight for Virtualization Enterprise Edition 8.9.3

Getting Started

The Foglight REST API is an application programming interface (API) that uses HTTP requests to GET, PUT, POST, and DELETE data.

The Foglight REST API Reference Guide is intended for users who have been assigned the API Access and the Administrator roles and who need programmatic access to easily create professional services and better integrate with third-party systems.

This section introduces you to the Foglight REST APIs. For more information, see the following topics:

•

Glossary

•

Prerequisites

•

Overview

Glossary

Table 1 explains the token that protects the access to REST APIs and is used as the request header for REST APIs. Auth-Token has been replaced with Access-Token in the Foglight Management Server 5.9.1, but Auth-Token is still supported. Quest recommends that you change to use Access-Token as the request header for REST APIs, as Auth-Token will be deprecated in future product release.


	NOTE: Retrieving the access token through authToken is only available in the Foglight release 5.7.5.7 or later.

Table 1. Glossary
	Description
Auth-Token (available in Foglight 5.7.5.7 and 5.7.5.8 releases only)	An Auth-Token is used as a request header for REST APIs, which protects the access to the REST APIs. This Auth-Token has been replaced with Access-Token since Foglight 5.9.1.
Access-Token (replaces Auth-Token starting with 5.9.1 release)	An Access-Token is used as a request header for REST APIs, which protects the access to the REST APIs.

Prerequisites

REST APIs are protected by authentications, which means you need retrieve an access token before using REST APIs. The authentications protecting REST APIs include the following two approaches:

•

User credentials: User account and user password

•

Access-Token: Token-based authentication

Use the Security — Login API to retrieve an access token through user credentials or an authToken, then include this access token in an HTTP request header to operate with REST APIs.


	NOTE: The minimum version required for operating REST APIs is Foglight Management Server 5.7.0. Retrieving an access token through authToken is only available in the Foglight release 5.7.5.7 or later.

For more information about how to use the Security — Login API with third party tools, visit the Foglight REST APIs Introduction - Java and Python Sample Code.

Overview

Table 2 lists the registry variables available after installing the Forge-RestAPI cartridge:

Table 2. Available registry variables

Registry variable name

Specifies whether the audit feature is enabled in the REST API. Enable is set by default. The audit logs can be found in the Audit dashboard.

REST_Audit_Filter

String

If the resource name is specified using this variable, audit logs of specified resources cannot be found in the Audit dashboard and the audit feature is disabled.

•

Separate multiple resource names with a comma.

•

Regular expression is also supported. The resource name is the part following "api" in the URL address. For example, for the URL address is http://<server>:<port>/api/v1/topology/query, the resource name is “v1/topology/query".

REST_DisabledAPI

String

Specifies the REST API that is disabled by default. “Run Script” is set by default, which means Script — Run Script will be disabled after the installation.

REST_MaxDepth

Integer

Specifies the expansion depth of a global object. This value starts from 0, and the default value is 1. Take the Host object as an example:

•

If the max depth is 0, the Host name and Host unique ID are returned.

•

If the max depth is 1, the first-level properties of the Host are returned.

REST_MaxObjectCount

Integer

Specifies how many objects are invoked through a response. An object is one instance that contains multiple properties.

REST_RetrieveMetricCurrentValue

Boolean

Specifies whether to retrieve the metric current value of a topology object in a response. False is set by default.

NOTE: If this registry variable is set to True, the Management Server will retrieve the metric current value only, while latest, period, and history values of this topology object will not be retrieved.

REST_RetrieveObservationValue

Boolean

Specifies whether to retrieve the observation current value of a topology object in a response. False is set by default.

REST_ShowLinks

Boolean

Specifies whether to show the link field through a response. False is set by default. The link field includes the following two types:

•

Link pointing to the object type

•

Link pointing to the object

REST_TokenExpirationTime

Integer

Specifies the token expiration time (in seconds). This variable takes effect when the token is accessed, when a login attempt using a new API or an API request is received on the server side, for example.

REST_CrossOriginResourceAllowedDomain

String

Specifies whether the request from the third-party integration site can be allowed. This variable has no default value.

REST_AccessControlAllowCredentials

Boolean

Specifies whether the response to a request can be exposed to the page. If the returned value is:

•

True: the response to a request can be exposed.

•

False: the response cannot be exposed.

REST_ShowTopologyTypeLocalProperties

Boolean

Specifies whether to show the property of Topology Object type in an instance. False is set by default.

REST_AgentSubmitInfoObservationDuration

Integer

Specifies the observation duration of the agents property in the RestAPIInfo type. The default value is 300, which is identical to 5 minutes.

REST_AgentSubmitInfoQueueSize

Integer

Specifies the cache size that stores the detailed information of submitted data. The default value is 100.

Most of registry variables listed in Table 3: URL parameters can be overwritten by the following URL parameters per request.

Table 3. URL parameters

URL parameter name

Description

maxObjectCount

Specifies how many objects are invoked through a response. An object is one instance that contains multiple properties.

maxDepth

Specifies the expansion depth of the global object. This value starts from 0, and the default value is 1. Take the Host object as an example:

•

If the max depth is 0, the Host name and Host unique ID are returned.

•

If the max depth is 1, the first-level properties of the Host are returned.

durationMS

Specifies the time duration, including startTimeMS and endTime. If startTimeMS is not set, the endTime value is used as the current time, and the startTime value is calculated as endTime minus the specified duration.

NOTE: This parameter does not impact the Topology — Observations query and Topology — TopologyObject query API.

startTimeMS

Specifies the startTime. The endTime is the sum of startTime and durationMS.

NOTE: This parameter does not impact the Topology — Observations query and Topology — TopologyObject query API.

retrieveMetricValue

Specifies whether to retrieve the metric current value of a Topology object in a response.

retrieveObservationValue

Specifies whether to retrieve the observation current value of a Topology object in a response.

showLinks

Specifies whether to show the link field through a response. False is set by default. The link field includes the following types:

•

Link pointing to the object type

•

Link pointing to the object

excludePropertyPatterns

Excludes the properties in a Topology object. Take http://<server>:<port>/api/v1/type/Host/instances?excludePropertyPatterns=.*Alarm.*,.*State.* as an example, this URL address excludes the properties which name contains "Alarm" and "State".

includePropertyPatterns

Includes the properties in a Topology object. Take http://<server>:<port>/api/v1/type/Host/instances?includePropertyPatterns=.*Alarm.*,.*State.* as an example, this URL address includes the properties which name contains "Alarm" and "State".

NOTE: If excludePropertyPatterns and includePropertyPatterns are set to the same value, the value set in excludePropertyPatterns is ignored.

showTopologyTypeLocalProperties

Specifies whether to show the property of the Topology type in an instance.