Foglight 6.0.0 - REST API Reference Guide

Authenticating with tokens

Foglight REST API requests require authentication via a token included in the request Header. Foglight can use two types of tokens:

•

Auth Token - You can authenticate with an Auth Token set in the Foglight Users & Security dashboard. This eliminates the need to pass your user credentials to Foglight.

Only one Auth Token can be associated with one Foglight user, and vice versa. A user with the Administrator role can reset or manage the Auth Token through the Foglight console.

•

Alternatively, a token can be retrieved with your user account and password. This token will expire 30 minutes after the last time it is used, after which you will need to request a new token.

Regardless of which approach is used to retrieve the session token, a successful response should be similar to the response in the image below.

Token usage

To authenticate API requests, include the Auth-Token field in your request header with the token value retrieved above.

REST API Foglight Registry Variables

The table below lists the registry variables used by the Foglight REST API. These variables are created by the Forge-RestAPI cartridge. These registry variables specify the default behavior of the REST API and can be modified by the parameters listed in Query Parameters.

Table 1. 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.

Query Parameters

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

Table 2. 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.