Using REST API

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

This section 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 covers the following key areas:

• Prerequisites
• Overview
• REST APIs
  • Agent
  • Alarm
  • Alarm Template API
  • App
  • Audit Log API
  • Cartridge
  • Open Telemetry API
  • Performance Investigator (PI) API
  • Query Insights
  • Registry
  • Remote client
  • Rule
  • Script
  • Security
  • Topology
  • TopologyType
  • User Information

The following table explains the token that protects the access to REST APIs and is used as the request header for REST APIs.

Glossary

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.

Overview

The following table lists the registry variables available after installing the Forge-RestAPI cartridge:

Available registry variables

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

URL parameters

REST APIs

This section provides you with essential information about available Foglight REST APIs. For more information, see the following topics:

• Agent
• Alarm
• Alarm Template API
• App
• Audit Log API
• Cartridge
• Open Telemetry API
• Performance Investigator (PI) API
• Query Insights
• Registry
• Remote client
• Rule
• Script
• Security
• Topology
• TopologyType
• User Information

App

The App related API includes the following:

• APP - Get App information

APP - Get App information

• API Name: Get App information
• Description: Get the application information.
• Request type: GET
• API path: /api/v1/
• Sample usage: https://<server>:<port>/api/v1/

Header:

Returned value:

Security

The Security related APIs include the following:

• Security - Login
• Security - Logout
• Security - Set Auth Token for a given user
• Security - Delete Auth Token for a given user
• Security - Set Auth Token for current user
• Security - Delete Auth Token for current user
  

Security - Login

• API Name: Login
• Description: Obtain an access token through user credentials (namely username and pwd in the Parameter: table) or a digital token (namely authToken in the Parameter: table).

• Request type: POST
• API path: /api/v1/security/login
• Sample usage: https://<server>:<port>/api/v1/security/login

Header:

Parameter:

Returned value:

Security - Logout

• API Name: Logout
• Description: Expire an access token.
• Request type: GET
• API path: /api/v1/security/logout
• Sample usage: https://<server>:<port>/api/v1/security/logout

Header:

Returned value:

Security - Set Auth Token for a given user

• API Name: Set Auth Token for a given user
• Description: Set the Auth Token, which is also referred to as digital token, for a specified user account. The current user who is logging in to REST service must have the Administrator permission to use this API.

After setting a token for the specified user, the old token (if exists) is expired. This causes the login status of this user is also expired, if this user has logged in to REST service. This user should log in to the REST service again using the new authToken or credentials.

• Request type: GET
• API path: /api/v1/security/setAuthToken/username
• Sample usage: https://<server>:<port>/api/v1/security/setAuthToken/abcuser

Header:

Parameter:

Returned value:

Security - Delete Auth Token for a given user

• API Name: Delete Auth Token for a given user
• Description: Delete the Auth Token, which is also referred to as digital token, for a specified user account. The current user who is logging in to REST service must have the Administrator permission to use this API.

After deleting a token for the specified user, the old token (if exists) is expired. This causes the login status of this user is also expired, if this user has logged in to REST service.

• Request type: GET
• API path: /api/v1/security/deleteAuthToken/username
• Sample usage: https://<server>:<port>/api/v1/security/deleteAuthToken/abcuser

Header:

Parameter:

Returned value:

Security - Set Auth Token for current user

• API Name: Set Auth Token for the current user
• Description: Set the Auth Token, which is also referred to as digital token, for the current login user.

After setting a token for the current user, the old token (if exists) is expired. This causes the login status of current user is also expired. The current user should log in to the REST service again using the new authToken or credentials.

• Request type: GET
• API path: /api/v1/security/setOwnAuthToken
• Sample usage: https://<server>:<port>/api/v1/security/setOwnAuthToken

Header:

Returned value:

Security - Delete Auth Token for current user

• API Name: Delete Auth Token for the current user
• Description: Delete the Auth Token, which is also referred to as digital token, for the current login user.

After deleting a token for the current user, the old token (if exists) is expired. This causes the login status of current user is also expired. The current user should log in to the REST service again using user credentials.

• Request type: GET
• API path: /api/v1/security/deleteOwnAuthToken
• Sample usage: https://<server>:<port>/api/v1/security/deleteOwnAuthToken

Header:

Returned value:

Agent

The Agent related APIs include the following:

• Agent - Get agent by agent ID
• Agent - Get all active agents
• Agent - Get all agents
• Agent - Get all inactive agents
• Agent - Start agent by agent ID
• Agent - Stop agent by agent ID
• Agent - Delete agent by agent ID

Agent - Get agent by agent ID

• API Name: Get agent by agent ID.
• Description: Filter out agents by the agent ID.
• Request type: GET
• API path: /api/v1/agent/agentId/agentId
• Sample usage: https://<server>:<port>/api/v1/agent/agentId/1

Header:

Returned value:

Agent - Get all active agents

• API Name: Get all active agents.
• Description: Filter out all active agents.
• Request type: GET
• API path: /api/v1/agent/active
• Sample usage: https://<server>:<port>/api/v1/agent/active

Header:

Returned value:

Agent - Get all agents

• API Name: Get all agents.
• Description: Get all agents.
• Request type: GET
• API path: /api/v1/agent/allAgents
• Sample usage: https://<server>:<port>/api/v1/agent/allAgents

Header:

Returned value:

Agent - Get all inactive agents

• API Name: Get all inactive agents.
• Description: Filter out all inactive agents.
• Request type: GET
• API path: /api/v1/agent/inactive
• Sample usage: https://<server>:<port>/api/v1/agent/inactive

Header:

Returned value:

Agent - Start agent by agent ID

• API Name: Start agent by agent ID.
• Description: Active agent and then start data collection by agent ID.
• Request type: POST
• API path: /api/v1/agent/start/agentId/:agentId
• Sample usage: https://<server>:<port>/api/v1/agent/start/agentId/1

Header:

Returned value:

Agent - Stop agent by agent ID

• API Name: Stop agent by agent ID.
• Description: Stop data collection and then deactivate agent by agent ID.
• Request type: POST
• API path: /api/v1/agent/stop/agentId/:agentId
• Sample usage: https://<server>:<port>/api/v1/agent/stop/agentId/1

Header:

Returned value:

Agent - Delete agent by agent ID

• API Name: Delete agent by agent ID.
• Description: Delete an agent by agent ID.
• Request type: DELETE
• API path: /api/v1/agent/delete/agentId/:agentId
• Sample usage: https://<server>:<port>/api/v1/agent/delete/agentId/1

Header:

Returned value:

Alarm

The Alarm related APIs include the following:

• Alarm - Acknowledge alarm by alarm ID
• Alarm - Clear alarm by alarm ID
• Alarm - Get alarm by alarm ID
• Alarm - Get alarm by rule ID
• Alarm - Get current alarms
• Alarm - Get history alarms
• Alarm - Get topology object current alarms
• Alarm - Get topology object history alarms
• Alarm - Push alarms
• Alarm - Push alarms by properties
• Alarm - Push alarms by query
  

Alarm - Acknowledge alarm by alarm ID

• API Name: Acknowledge alarm by alarm ID
• Description: Acknowledge an alarm by its ID.
• Request type: GET
• API path: /api/v1/alarm/ack/alarmId
• Sample usage: https://<server>:<port>/api/v1/alarm/ack/1f478dec-f920-4da9-a8d2-b9ba0dcd4394

Header:

Returned value:

Alarm - Clear alarm by alarm ID

• API Name: Clear alarm by alarm ID
• Description: Clear an alarm by its ID.
• Request type: GET
• API path: /api/v1/alarm/clear/alarmId
• Sample usage: https://<server>:<port>/api/v1/alarm/clear/1f478dec-f920-4da9-a8d2-b9ba0dcd4394

Header:

Returned value:

Alarm - Get alarm by alarm ID

• API Name: Get alarm by alarm ID
• Description: Filter out alarms by alarm ID.
• Request type: GET
• API path: /api/v1/alarm/alarmId
• Sample usage: https://<server>:<port>/api/v1/alarm/1f478dec-f920-4da9-a8d2-b9ba0dcd4394

Header:

Returned value:

Alarm - Get alarm by rule ID

• API Name: Get alarm by rule ID.
• Description: Filter out alarms by a rule ID. Time range is the default value set in the Management Server, and you can customize the time range using the startTimeMS and durationMS parameter.
• Request type: GET
• API path: /api/v1/alarm/ruleId/ruleId
• Sample usage: https://<server>:<port>/api/v1/alarm/ruleId/se478dec-f920-4de9-a8d2-b9ba0dcasd94

Header:

Returned value:

Alarm - Get current alarms

• API Name: Get current alarms
• Description: Filter out current alarms.
• Request type: GET
• API path: /api/v1/alarm/current
• Sample usage: https://<server>:<port>/api/v1/alarm/current

Header:

Returned value:

Alarm - Get history alarms

• API Name: Get history alarms
• Description: Filter out all history alarms.
• Request type: GET
• API path: /api/v1/alarm/history
• Sample usage: https://<server>:<port>/api/v1/alarm/history

Header:

Returned value:

Alarm - Get topology object current alarms

• API Name: Get topology object current alarms
• Description: Filter out current alarms by the ID of a topology object.
• Request type: GET
• API path: /api/v1/alarm/current/topologyId
• Sample usage: https://<server>:<port>/api/v1/alarm/current/se478dec-f920-4de9-a8d2-b9ba0dcasd94

Header:

Returned value:

Alarm - Get topology object history alarms

• API Name: Get topology object history alarms
• Description: Filter out history alarms by the ID of a topology object.
• Request type: GET
• API path: /api/v1/alarm/history/topologyId
• Sample usage: https://<server>:<port>/api/v1/alarm/history/se478dec-f920-4de9-a8d2-b9ba0dcasd94

Header:

Returned value:

Alarm - Push alarms

• API Name: Push alarms
• Description: Push an alarm to an existing topology object, and the imported alarm will show on the Alarm dashboard. The “topologyObjectId” field is mandatory and the “ruleId” field is optional. This API set the value of “ruleId” to ExternalAlarm by default, if this field is not set. If you invoke this API using both fields, ensure that ruleId is properly defined to link with its topologyObjectId; otherwise the alarm might be imported into a wrong topology object. Consider for example a rule “CPU Utilization” is related to the “HostCPUs” object. If you define topologyObjectId to Host, this API imports CPU Utilization to the Host object. Postman provides “Alarm - Push Alarm XML” and “Alarm - Push Alarm JSON” sample codes for reference. Click here to download and import the sample codes.
• Request type: POST
• API path: /api/v1/alarm/pushAlarm

Sample usage: When using the pushAlarm API, note the following:

• Make sure to use the following as the value of alarmMessage: AAA. BBB. AAA represents the title of the alarm dialog box, while BBB stands for the alarm message. Make sure to add a space between “.” and “BBB”.
• To get the value of ruleId, do either of the following:
  • Invoke the Rule - Get all rules’ data API.
  • Execute the following scripts in the Administration > Tooling > Script Console dashboard:

def ruleName = <RULE_NAME>
def rule = server.RuleService.getAllRules().find{ it.name == ruleName }

if(rule){ 
    return rule.id;
}else{
    return "Rule not found."
}

The following illustrates the sample code of request body in XML and JSON separately.

Request body in XML:

<externalAlarmParamBean>
<alarmMessage>title of alarm dialog. alarm message</alarmMessage>
<severity>3</severity>
<topologyObjectId>94e27d92-08a5-4c28-9a90-8856a7689105</topologyObjectId>
<ruleId>c83632ae-3468-4ac1-bd69-523595e18750</ruleId>
</externalAlarmParamBean>

Request body in JSON:

{"alarmMessage":"title of alarm dialog. alarm message", "severity":"2", "topologyObjectId":"94e27d92-08a5-4c28-9a90-8856a7689105"}

Severity value:

Header:

Returned value:

Alarm - Push alarms by properties

• API Name: Push alarms by properties
• Description: Push alarms based on the properties of a topology object.
• Request type: POST
• API path: /api/v1/alarm/pushAlarmByProperties

Sample usage: The following illustrates the sample code of request body in XML and JSON separately.

Request body in XML:

<externalAlarmParamBean>
<alarmMessage>Test Alarm.This is a test alarm message from postman</alarmMessage>
<severity>3</severity>
<type>Host</type>
<properties>
<entry>
<key>name</key>
<value>nameofHost</value>
</entry>
</properties>
</externalAlarmParamBean>

Request body in JSON:

{"alarmMessage":"This is a test alarm message from postman. asdfasdf", "severity":"2", "type":"Host", "properties":{"name":"nameofHost"}, "ruleId":"72b73d98-8c6c-4ee1-b5ba-fd7c14645280"}

Alarm - Push alarms by query

• API Name: Push alarms by query
• Description: Push alarms using the query.
• Request type: POST
• API path: /api/v1/alarm/pushAlarmByQuery

Sample usage: The following illustrates the sample code of request body in XML and JSON separately.

Request body in XML:

<externalAlarmParamBean>
<alarmMessage>Test Alarm.This is a test alarm message from postman</alarmMessage>
<severity>3</severity>
<query>!Host:name="nameofHost"</query>
</externalAlarmParamBean>

Request body in JSON:

{"alarmMessage":"This is a test alarm message from postman. asdfasdf", "severity":"2", "query":"!Host:name='nameofHost'"}

Alarm Template API

The Alarm Template API related operations include the following:

• Alarm Template - Get all alarm templates
• Alarm Template - Get alarm template by ID
• Alarm Template - Create alarm template
• Alarm Template - Update alarm template
• Alarm Template - Delete alarm template

Alarm Template - Get all alarm templates

• API Name: Get all alarm templates
• Description: Retrieve all alarm templates configured in the system.
• Request type: GET
• API path: /api/v1/alarm-templates
• Sample usage: https://<server>:<port>/api/v1/alarm-templates

Header:

Returned value:

Alarm Template - Get alarm template by ID

• API Name: Get alarm template by ID
• Description: Retrieve a specific alarm template by its unique identifier.
• Request type: GET
• API path: /api/v1/alarm-templates/{id}
• Sample usage: https://<server>:<port>/api/v1/alarm-templates/template-123

Header:

Parameter:

Returned value:

Alarm Template - Create alarm template

• API Name: Create alarm template
• Description: Create a new alarm template in the system.
• Request type: POST
• API path: /api/v1/alarm-templates
• Sample usage: https://<server>:<port>/api/v1/alarm-templates

Header:

Returned value:

Alarm Template - Update alarm template

• API Name: Update alarm template
• Description: Update an existing alarm template.
• Request type: PUT
• API path: /api/v1/alarm-templates/{id}
• Sample usage: https://<server>:<port>/api/v1/alarm-templates/template-123

Header:

Parameter:

Returned value:

Alarm Template - Delete alarm template

• API Name: Delete alarm template
• Description: Delete an existing alarm template by its ID.
• Request type: DELETE
• API path: /api/v1/alarm-templates/{id}
• Sample usage: https://<server>:<port>/api/v1/alarm-templates/template-123

Header:

Parameter:

Returned value:

Audit Log API

The Audit Log API related operations include the following:

• Audit Log - Query audit logs
• Audit Log - Get audit log by ID

Audit Log - Query audit logs

• API Name: Query audit logs
• Description: Query audit logs using various criteria and filters.
• Request type: POST
• API path: /api/v1/audit-logs/query
• Sample usage: https://<server>:<port>/api/v1/audit-logs/query

Header:

Returned value:

Audit Log - Get audit log by ID

• API Name: Get audit log by ID
• Description: Retrieve a specific audit log entry by its unique identifier.
• Request type: GET
• API path: /api/v1/audit-logs/{record-id}
• Sample usage: https://<server>:<port>/api/v1/audit-logs/record-123

Header:

Parameter:

Returned value:

Open Telemetry API

The Open Telemetry API related operation includes the following:

• Open Telemetry — Get metrics

Open Telemetry — Get metrics

• API Name: Get metrics
• Description: Retrieve OpenTelemetry metrics from the Foglight system.
• Request type: GET
• API path: /api/v1/open-telemetry/metrics
• Sample usage: https://<server>:<port>/api/v1/open-telemetry/metrics

Header:

Returned value:

Performance Investigator (PI) API

The Performance Investigator (PI) API provides comprehensive database performance monitoring capabilities that help identify performance bottlenecks and optimize query execution. These APIs allow you to retrieve detailed performance statistics, execution plans, dimension trees, and monitoring metrics for supported database platforms including SQL Server, Oracle, Azure SQL, MySQL, and PostgreSQL.

The Performance Investigator API supports the following database domains: SQL_SERVER, ORACLE, SSAS, AZURE, MYSQL, POSTGRES.

The Performance Investigator API related operations include the following:

• PI — Get instance list
• PI — Get dimension tree
• PI — Get resource categories
• PI — Get resource breakdown summary
• PI — Get active time baseline
• PI — Get list metrics
• PI — Get top dimension values
• PI — Get metric data
• PI — Get instance info
• PI — Get granularity timeframe
• PI — Get locked object overview
• PI — Get highlights
• PI — Get execution plan
• PI — Get execution plan permission
• PI — Get database list
• PI — Get blocked sessions
• PI — Get wait events
• PI — Query explorer search
• PI — Get PI domains
• PI — Get query explorer dimensions
• PI — Query explorer search by text
• PI — Query explorer search by top
• PI — Create direct link
• PI — Get available actions
• PI — Decompress
• PI — Remove literals

PI — Get instance list

• API Name: Get instance list
• Description: Retrieve the PI instance names and metadata for a specific database domain.
• Request type: GET
• API path: /api/v1/spi/getInstanceList/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getInstanceList/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get dimension tree

• API Name: Get dimension tree
• Description: Retrieve the PI dimension tree structure for performance analysis grouping and filtering.
• Request type: POST
• API path: /api/v1/spi/getDimensionTree/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getDimensionTree/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get resource categories

• API Name: Get resource categories
• Description: Retrieve available resource categories for performance analysis (e.g., CPU, I/O, Memory).
• Request type: POST
• API path: /api/v1/spi/getResourceCategory/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getResourceCategory/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get resource breakdown summary

• API Name: Get resource breakdown summary
• Description: Get the values (sum, percent, etc.) of each wait category as well as other useful metrics, and the list of points for the Breakdown graph. Note: for SQL Server, currently tested only for Instance level Node.
• Request type: POST
• API path: /api/v1/spi/getResourceBreakdownSummary/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getResourceBreakdownSummary/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get active time baseline

• API Name: Get active time baseline
• Description: Get the values (sum, percent, etc.) of each wait category and their baseline values, as well as the list of points for the Baseline graph.
• Request type: POST
• API path: /api/v1/spi/getActiveTimeBaseline/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getActiveTimeBaseline/POSTGRES?startTime=1720171551000&endTime=1720175151000&piWaitStatisticsObjectId=2e1c6786-ec2b-4b49-9b5b-7a1c91faaece

Header:

Parameter:

Returned value:

PI — Get list metrics

• API Name: Get list metrics
• Description: Get list of available metrics. Note: Not yet fully implemented.
• Request type: POST
• API path: /api/v1/spi/getListMetrics/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getListMetrics/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get top dimension values

• API Name: Get top dimension values
• Description: Retrieve the top performing queries, users, applications, or other dimension values based on resource consumption.
• Request type: POST
• API path: /api/v1/spi/getTopDimensionValues/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getTopDimensionValues/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get metric data

• API Name: Get metric data
• Description: Retrieve detailed metric data and historical values for performance analysis.
• Request type: POST
• API path: /api/v1/spi/getMetricData/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getMetricData/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get instance info

• API Name: Get instance info
• Description: Get information for a specific PI instance.
• Request type: POST
• API path: /api/v1/spi/getInstanceInfo/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getInstanceInfo/POSTGRES?startTime=1720091626000&endTime=1720178026000&piAgentId=63

Header:

Parameter:

Returned value:

PI — Get granularity timeframe

• API Name: Get granularity timeframe
• Description: Get the aggregation level (what table/s will Foglight search for the specified time frame).
• Request type: POST
• API path: /api/v1/spi/getGranularityTimeframe/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getGranularityTimeframe/POSTGRES?startTime=1727255624025&endTime=1727259224025

Header:

Parameter:

Returned value:

PI — Get locked object overview

• API Name: Get locked object overview
• Description: Get the overview table data for Dimension Tree items under Locked Object dimension.
• Request type: POST
• API path: /api/v1/spi/getLockedObjectOverview/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getLockedObjectOverview/POSTGRES?startTime=1722932199000&endTime=1722936428332

Header:

Parameter:

Returned value:

PI — Get highlights

• API Name: Get highlights
• Description: Get the most consumed resource for the specific Instance. Note: currently implemented only for SQL Server Instance level and “WORKLOAD” waitCategory.
• Request type: POST
• API path: /api/v1/spi/getHighlights/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getHighlights/SQL_SERVER?startTime=1745258505000&endTime=1745262105000

Header:

Parameter:

Returned value:

PI — Get execution plan

• API Name: Get execution plan
• Description: Retrieve database execution plans for query optimization analysis.
• Request type: POST
• API path: /api/v1/spi/getExecutionPlan/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getExecutionPlan/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get execution plan permission

• API Name: Get execution plan permission
• Description: Get a list of flags indicating if there are sufficient permissions to execute the Execution Plan.
• Request type: POST
• API path: /api/v1/spi/getExecutionPlanPermission/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getExecutionPlanPermission/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get database list

• API Name: Get database list
• Description: Get a list of databases with indication for each database if it has record of the specified statement ID in the given time frame.
• Request type: POST
• API path: /api/v1/spi/getDatabaseList/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getDatabaseList/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get blocked sessions

• API Name: Get blocked sessions
• Description: Retrieve information about blocked database sessions and blocking chains.
• Request type: POST
• API path: /api/v1/spi/getBlockedSessions/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getBlockedSessions/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get wait events

• API Name: Get wait events
• Description: Retrieve top database wait events that are impacting performance.
• Request type: POST
• API path: /api/v1/spi/getWaitEvents/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getWaitEvents/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Query explorer search

• API Name: Query explorer search by text
• Description: Search PI queries by text snippet to find specific statements or patterns.
• Request type: POST
• API path: /api/v1/spi/getQueryExplorerResultsByText/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getQueryExplorerResultsByText/SQL_SERVER

Header:

Parameter:

Returned value:

PI — Get PI domains

• API Name: Get PI domains
• Description: Retrieve the list of PI Domains supporting REST API on this FMS (Domain name for REST API URL + Domain display name for AUI).
• Request type: GET
• API path: /api/v1/spi/getPiDomains
• Sample usage: https://<server>:<port>/api/v1/spi/getPiDomains

Header:

Returned value:

PI — Get query explorer dimensions

• API Name: Get query explorer dimensions
• Description: Query Explorer - Retrieve the list of dimensions.
• Request type: GET
• API path: /api/v1/spi/getQueryExplorerDimensions/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getQueryExplorerDimensions/POSTGRES

Header:

Parameter:

Returned value:

PI — Query explorer search by text

• API Name: Query explorer search by text
• Description: Query Explorer - Retrieve the statements containing the selected text fragment and filter by selected dimensions.
• Request type: POST
• API path: /api/v1/spi/getQueryExplorerResultsByText/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getQueryExplorerResultsByText/SQL_SERVER?startTime=1746527008000&endTime=1746627008000

Header:

Parameter:

Returned value:

PI — Query explorer search by top

• API Name: Query explorer search by top
• Description: Query Explorer - Retrieve the top statements ordered by resource and filter by selected dimensions.
• Request type: POST
• API path: /api/v1/spi/getQueryExplorerResultsByTop/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getQueryExplorerResultsByTop/SQL_SERVER?startTime=1746527008000&endTime=1746627008000

Header:

Parameter:

Returned value:

PI — Create direct link

• API Name: Create direct link
• Description: Query Explorer - create a link with all the query details.
• Request type: POST
• API path: /api/v1/spi/createDirectLink/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/createDirectLink/SQL_SERVER?startTime=1740366783112&endTime=1747835390846

Header:

Parameter:

Returned value:

PI — Get available actions

• API Name: Get available actions
• Description: Query Explorer - Get available actions plus the URL according to the domain type.
• Request type: POST
• API path: /api/v1/spi/getQueryAvailableActions/{domainName}
• Sample usage: https://<server>:<port>/api/v1/spi/getQueryAvailableActions/SQL_SERVER?startTime=1748167200000&endTime=1748253600000

Header:

Parameter:

Returned value:

PI — Decompress

• API Name: Decompress
• Description: Decompress encoded text, used to decode the full SQL text from the SQL hash.
• Request type: POST
• API path: /api/v1/spi/decompress
• Sample usage: https://<server>:<port>/api/v1/spi/decompress

Header:

Request body (JSON):

{
    "data": "hashvalue"
}

Returned value:

PI — Remove literals

• API Name: Remove literals
• Description: Remove literals from a full SQL query.
• Request type: POST
• API path: /api/v1/spi/removeLiterals
• Sample usage: https://<server>:<port>/api/v1/spi/removeLiterals

Header:

Request body (JSON):

{
    "data": "sqlQuery"
}

Returned value:

Query Insights

The Query Insights APIs provide access to TopSQL performance data, allowing you to retrieve and analyze the top-performing SQL queries across your database environment. These APIs enable you to identify performance bottlenecks and optimize query performance.

The Query Insights related APIs include the following:

• Query Insights — Get TopSQL data
• Query Insights — Get SQL full text

Query Insights — Get TopSQL data

• API Name: Get TopSQL data
• Description: Retrieve top SQL queries ranked by impact across database domains. Provides filtering, sorting, and pagination capabilities for performance analysis.
• Request type: POST
• API path: /api/v1/topsql
• Sample usage: https://<server>:<port>/api/v1/topsql

Header:

Request body (JSON):

{
    "domains": ["mssql", "oracle"],
    "startTime": 1640995200000,
    "endTime": 1641002400000,
    "rows": 50,
    "textFilter": "SELECT",
    "targetName": "MyServer",
    "sortColumn": "IMPACT",
    "sortOrder": "DESC",
    "impactMin": 1.0,
    "impactMax": 100.0,
    "responseTimeMin": 100.0,
    "responseTimeMax": 5000.0,
    "elapsedTimeMin": 50.0,
    "elapsedTimeMax": 10000.0,
    "executionsMin": 1,
    "executionsMax": 1000
}

Parameter:

Returned value:

TopSQL Result Object:

Example Response:

{
    "availableDomains": ["SQL_SERVER", "ORACLE", "MYSQL"],
    "topSqlResults": [
        {
            "sqlText": "SELECT * FROM users WHERE id = ?",
            "sqlId": "abc123",
            "sqlIDDisplayName": "User Query",
            "domainName": "SQL_SERVER",
            "targetName": "ProductionDB",
            "overviewURL": "/aui/wcf?name=SQL_SERVER_Instance_Overview&objectid=12345",
            "performanceURL": "/aui/wcf?name=SQL_SERVER_Performance&objectid=12345",
            "impact": "15.5",
            "elapsedTime": "2500.0",
            "executions": "1250",
            "responseTime": "2.0",
            "objectId": "obj_12345",
            "isFullTextApiAvailable": true
        }
    ]
}

Query Insights — Get SQL full text

• API Name: Get SQL full text
• Description: Retrieve the complete SQL text for a specific query by domain, object ID, and SQL ID.
• Request type: POST
• API path: /api/v1/topsql/full-text
• Sample usage: https://<server>:<port>/api/v1/topsql/full-text

Header:

Request body (JSON):

{
    "objectId": "obj_12345",
    "sqlId": "abc123",
    "domainName": "mssql"
}

Parameter:

Returned value:

Example Response:

{
    "result": "SELECT u.id, u.username, u.email, p.profile_data FROM users u LEFT JOIN profiles p ON u.id = p.user_id WHERE u.id = ? AND u.active = 1"
}

Error Responses:

Cartridge

The Cartridge related APIs include the following:

• Cartridge - Get all cartridges’ data
• Cartridge - Get all core cartridges’ data
• Cartridge - Get all non-core cartridges’ data
  

Cartridge - Get all cartridges’ data

• API Name: Get all cartridge’s data
• Description: Get data of all cartridges.
• Request type: GET
• API path: /api/v1/cartridge/allCartridges
• Sample usage: https://<server>:<port>/api/v1/cartridge/allCartridges

Header:

Returned value:

Cartridge - Get all core cartridges’ data

• API Name: Get all core cartridge’s data
• Description: Get data of all the core cartridges.
• Request type: GET
• API path: /api/v1/cartridge/allCartridges/core
• Sample usage: https://<server>:<port>/api/v1/cartridge/allCartridges/core

Header:

Returned value:

Cartridge - Get all non-core cartridges’ data

• API Name: Get all non-core cartridge’s data
• Description: Get data of all the non-core cartridges.
• Request type: GET
• API path: /api/v1/cartridge/allCartridges/nonCore
• Sample usage: https://<server>:<port>/api/v1/cartridge/allCartridges/nonCore

Header:

Returned value:

Registry

The Registry related API includes the following:

• Registry - Get all registries’ data
  

Registry - Get all registries’ data

• API Name: Get all registries’ data
• Description: Get data of all registries.
• Request type: GET
• API path: /api/v1/registry/allRegistries
• Sample usage: https://<server>:<port>/api/v1/registry/allRegistries

Header:

Returned value:

Remote client

The Remote related API includes the following:

• Remote client - Get all remote clients’ data
  

Remote client - Get all remote clients’ data

• API Name: Get all remote clients’ data
• Description: Get data of all the remote clients.
• Request type: GET
• API path: /api/v1/remoteClient/allRemoteClients
• Sample usage: https://<server>:<port>/api/v1/remoteClient/allRemoteClients

Header:

Returned value:

Rule

The Rule related APIs include the following:

• Rule - Get all rules’ data
• Rule - Get rule by id
  

Rule - Get all rules’ data

• API Name: Get all rules’ data
• Description: Get data of all rules.
• Request type: GET
• API path: /api/v1/rule/allRules
• Sample usage: https://<server>:<port>/api/v1/rule/allRules

Header:

Returned value:

Rule - Get rule by id

• API Name: Get rule by ID
• Description: Filter out rules by a rule ID.
• Request type: GET
• API path: /api/v1/rule/ruleId
• Sample usage: https://<server>:<port>/api/v1/rule/ruleId

Header:

Returned value:

Script

The Script related APIs include the following:

• Script - Run script
  

Script - Run script

• API Name: Run script
• Description: Run a script in the Management Server.

• Request type: POST
• API path: /api/v1/script/runScript

Sample usage: If you use & in your sample codes, make sure to convert it to &

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

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

JSON:

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

XML:

<ScriptBean>
<script>System.err.println("Hello World!");</script>
</ScriptBean>

The complete format is as below:

JSON:

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

XML:

<ScriptBean>
<script>#utilization#</script>
<cartridgeName>Infrastructure</cartridgeName>
<scopeObjectId>3ebb2158-e5e9-4403-be3c-46fd8020efeb</scopeObjectId>
</ScriptBean>

Header:

Returned value:

Topology

The Topology related APIs include the following:

• Get properties’ value
• Get property value
• Get topology object by id
• Get topology object by ids
• Observations query
• TopologyObject query
• Push data

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.
• Request type: GET
• API path: /api/v1/topology/topologyId/paths
• Sample usage: https://<server>:<port>/api/v1/topology/3546fa55-11b6-4943-b7cb84ddcf350bc5/paths?path=name&path=uniqueId&path=utilization

Header:

Parameter:

Returned Value:

Get property value

• 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.
• Request type: GET
• API path: /api/v1/topology/topologyId/path
• Sample usage: https://<server>:<port>/api/v1/topology/abc94b3d-f599-4766-a979-f32d372ff47d/cpus/utilization

Header:

Returned Value:

Get topology object by id

• API Name: Get topology object by ID
• Description: Filter out topology objects by an object ID.
• Request type: GET
• API path: /api/v1/topology/topologyObjectId
• Sample usage: https://<server>:<port>/api/v1/topology/1f478dec-f920-4da9-a8d2-b9ba0dcd4394

Header:

Returned Value:

Get topology object by ids

• API Name: Get topology object by ids
• Description: Filter out topology objects by multiple IDs.
• Request type: GET
• API path: /api/v1/topology/topologyIds
• Sample usage: https://<server>:<port>/api/v1/topology/topologyIds?Id=3546fa55-11b6-4943-b7cb84ddcf350bc5&Id=67beea68-fa6f-4cd3-b122-dcb20db50360

Header:

Parameter:

Returned Value:

Observations query

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

• Request type: POST
• API path: /api/v1/topology/batchQuery
• Sample usage: Generate a post request using the following URL: https://<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:

JSON:

{
"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"
}

XML:

<observationQueryParamBean>
<endTime>1477988816209</endTime>
<granularity>3600000</granularity>
<includes>
<ids>ca83d1a2-f04b-483d-b224-055967777e72</ids>
<observationName>utilization</observationName>
</includes>
<includes>
<ids>f58f36ef-88ef-4264-9b8a-91df79fd37e9</ids>
<observationName>utilization</observationName>
</includes>
<includes>
<ids>f3df86e1-0718-4ccf-ae05-c25414b53db9</ids>
<ids>7910afd1-0247-4309-bae4-05f9419ab719</ids>
<ids>4ed2b409-cf18-4c14-a6ab-fdc19cff006e</ids>
<observationName>percentMemory</observationName>
</includes>
<numberOfValue>1</numberOfValue>
<retrievalType>AGGREGATE_AND_LAST</retrievalType>
<startTime>1477985216208</startTime>
</observationQueryParamBean>

Header:

Parameter:

Returned Value:

TopologyObject query

• API Name: TopologyObject query
• Description: Filter out topology objects by a batch query.
• Request type: POST
• API path: /api/v1/topology/query
• Sample usage: Generate a post request using the following URL: https://<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:

JSON:

{ 
"queryText":"!Host",
"caseSensitive":true,
"freshnessFactor":3600000.0,
"params":[{"name":"name","value":"nameofHost"},{"name":"domainName","value":"nameofDomain"}],
"queryTopologyObjects":true,
"requiresCoherentResults":true,
"scopingTopologyObjectId":"4f888425-a734-4bee-a5a7-4e24cd3c83cd",
"transactionTimestampMillis":3600000,
"timeRangeStartTime":1477984060722,
"timeRangeEndTime":1477987094482,
"timeRangeGranularity":3600000,
"timeRangeMaxPoints":500
}

XML:

<queryParamBean>
<caseSensitive>true</caseSensitive>
<freshnessFactor>3600000.0</freshnessFactor>
<params>
<name>name</name>
<value>nameofHost</value>
</params>
<params>
<name>domainName</name>
<value>nameofDomain</value>
</params>
<queryText>!Host</queryText>
<queryTopologyObjects>true</queryTopologyObjects>
<requiresCoherentResults>true</requiresCoherentResults>
<scopingTopologyObjectId>4f888425-a734-4bee-a5a7-4e24cd3c83cd</scopingTopologyObjectId>
<transactionTimestampMillis>3600000</transactionTimestampMillis>
<timeRangeStartTime>1477984060722</timeRangeStartTime>
<timeRangeEndTime>1477987094482</timeRangeEndTime>
<timeRangeGranularity>3600000</timeRangeGranularity>
<timeRangeMaxPoints>500</timeRangeMaxPoints>
</queryParamBean>

Header:

Parameter:

Returned Value:

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:

{
"data":[{
"typeName": "TypeName",
"properties": {
"simplePropertyName": "TestData1",
"MetricPropertyName": 11234,
"ObservationPropertyName": {
"simplePropertyNameOne": "testObservation1",
"simplePropertyNameTwo": 1495447993592,
"simplePropertyNameThree": 1495447993592
}
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}

When invoking this API, note the following:

• 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. For more information, refer to the Sample usage section below.
• The identity of Host type (hostId) is generated 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();

• Request type: POST
• API path: /api/v1/topology/pushData

Header:

Parameter:

Returned Value:

Sample usage:

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.

{
"data":[{
"typeName": "FSMAgentBlackout",
"properties": {
"name" : "Test-FSMAgentBlackout"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}

Case 2: Create a Host instance. If you want to submit Host type data, the name property is mandatory while vmId and systemId properties 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.

{
"data":[{
"typeName": "Host",
"properties": {
"hostId" : "Test-Host",
"name" : "Test-Host"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}

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.

{
"data":[{
"typeName": "HostProcess",
"properties": {
"os" : "e197ee1a-a60d-4627-8313-72d6bd49ce61",
"name" : "Test-HostProcess"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}

Case 4: Create a custom type instance. Consider for example we have imported the below type definition in the Add Topology Type dashboard.

<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
</type>

The identity property is name in the above type definition. Use the following request body to create the custom type instance:

{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "Test-PushDataTest"
}
}],
"startTime": 1495180240539,
"endTime": 1495180540539,
"agentName": "sampleagent"
}

Case 5: Consider for example we have the following type definition.

<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
<property name='testMetric' type='Metric' is-containment='true' unit-name='count' />
</type>

Use the following request body to push metrics.

{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "Test-PushDataTest",
"testMetric" : 100
}
}],
"startTime": 1499830726959,
"endTime": 1499830786959,
"agentName": "sampleagent"
}

If you still see your metrics after the metrics push, check the server log to see if you see any “Discarded value” warning.

Case 6: Consider for example we have the following type definition.

<type name='PushDataTest' extends='TopologyObject'>
<property name='name' type='String' is-identity='true'/>
<property name='testMetric' type='Metric' is-containment='true' unit-name='count' />
<property name='testObservation' type='TestObservation' is-containment='true' unit-name='count' />
</type>
<type name='TestObservation' extends='ComplexObservation'>
<property name='current' type='TestObservationValue' is-many='false' is-containment='true' />
<property name='latest' type='TestObservationValue' is-many='false' is-containment='true' />
<property name='history' type='TestObservationValue' is-many='true' is-containment='true' />
</type>
<type name='TestObservationValue' extends='ObservedValue'>
<property name='value' type='TestObject' is-containment='true'/>
</type>
<type name='TestObject' extends='DataObject'>
<property name='testName' type='String' />
<property name='createDate' type='Date' />
<property name='createTime' type='Double' />
</type>

Use the following request body to push observations.

{
"data":[{
"typeName": "PushDataTest",
"properties": {
"name" : "PushDataTest",
"testMetric": 112233,
"testObservation": {
"testName" : "testObservation",
"createDate": 1495447993592,
"createTime": 1495447993592
}
}
}],
"startTime": 1499839494614,
"endTime": 1499839554614,
"agentName": "sampleagent"
}

TopologyType

The TopologyType related operations enable you to:

• Get type information
• Get type super type’s information
• Get all instances of a type

Get type information

• API Name: Get type information
• Description: Returns type information for a specified type name.
• Request type: GET
• API path: /api/v1/type/typeName
• Sample usage: https://<server>:<port>/api/v1/type/Host
• URI parameters: typeName (string) - The name of the topology type

Header:

Returned Value:

Get type super type’s information

• API Name: Get type super type’s information
• Description: Returns super type information for a specified type name.
• Request type: GET
• API path: /api/v1/type/typeName/super
• Sample usage: https://<server>:<port>/api/v1/type/Host/super
• URI parameters: typeName (string) - The name of the topology type

Header:

Returned Value:

Get all instances of a type

• API Name: Get all instances of a type
• Description: Returns all instances of a specified type.
• Request type: GET
• API path: /api/v1/type/typeName/instances
• Sample usage: https://<server>:<port>/api/v1/type/Host/instances
• URI parameters: typeName (string) - The name of the topology type

Header:

Returned Value:

User Information

Get current user information

• API Name: Get current user information
• Description: Returns information about the currently authenticated user, including user ID, user name, and role information.
• Request type: GET
• API path: /api/v1/user/current
• Sample usage: https://<server>:<port>/api/v1/user/current

Header:

Returned Value: