Rest API – Visual Controls
Overview
The REST API allows you to work with Graphs (called Visual Controls in SPM) using a REST Client in lieu of the FireScope user interface. Below you'll find documentation for the following operations.
- Direct Fetch
- Schema
- Search
- Create or Update
- Delete
Direct Fetch
To retrieve the current data for a Graph as a JSON document, send a GET request with the following URL format:
https://localhost:38060/web_services/graphs?account=yourAccount&name=yourGraphName
Be sure to change the domain name (localhost
) and query parameters (account
, name
) values to match your environment and data.
Query Parameter Descriptions
Property | Description | Type | Required |
---|---|---|---|
account | Name of the FireScope Account. | String | Yes |
name | Name of the Graph. | String | Yes |
Schema
To retrieve the full schema of a Graph object, with all available fields, their data types, enumeration values, and read/write permissions, send a GET request with the following URL format:
https://localhost:38060/web_services/graphs?account=yourAccount&schema=true
Be sure to change the domain name (localhost
) and query parameter (account
) value to match your environment and data.
Schema Parameter Descriptions
Property | Description | Type | Required |
---|---|---|---|
account | Name of the FireScope Account. | String | Yes |
schema | If true , the response will contain the full schema of the object with all available fields, their data types, potential enumeration values, and read/write permissions. |
Boolean | Yes |
Search
Search is not supported for this REST API endpoint.
Create or Update
To create or update a Graph, send a POST request with a JSON document containing the specific Graph information to the following URL:
https://localhost:38060/web_services/graphs
Be sure to change the domain name (localhost
) to match your environment and data.
You can use the following example as a guide, but note that it does not include all optional properties. See the full list after the example.
{ "account_id": "firescope", "dashboard_created_userid": null, "fs_gauge": 0, "fs_multiaxis": 0, "graphtype": 0, "name": "Latency", "graphs_attributes": [ { "attributeid": { "edge_device": "Edge 1", "ci": "MININT-GVTTN4V", "attribute": "response_time" }, "color": "009900", "drawtype": 1, "sortorder": 0, "type": 0 } ], "markers": [ { "attributeid": { "edge_device": "Edge 1", "ci": "MININT-GVTTN4V", "attribute": "response_time" }, "label": "Warning", "value": 500, "color": "#00FF00" } ] }
Property Descriptions
The following table provides information about all the required and optional properties available for a Graph.
The following tables only include fields that can be modified through the API that will be used. They do not include descriptions of all available fields in an object. See the Schema API call for a list of all possible fields available and their data types.
Property | Description | Type | Default | Required |
---|---|---|---|---|
account_id | Name of the FireScope Account. | String | Yes | |
fs_gauge | The Graph Display Mode. Possible values:
|
Number | 0 |
Yes |
graphs_attributes | Array of one or more Graph Attribute objects to plot. See Graph Attribute Object below. | Object[] | Yes | |
graphtype | The type of Graph to generate. Possible values:
|
Number | 0 |
Yes |
name | A unique and descriptive name for the Graph. | String | Yes | |
dashboard_created_user_id | Name of the FireScope User to whom this Graph belongs for Dashboard use | String | null |
No |
fs_multiaxis | A modifier to change the display of the Graph based on the graphtype value.
|
Number | 0 |
No |
markers | Array of optional Annotation Markers to set at specific values for a the specified Attribute. See Marker Object below. Available with graphtype :
|
Object[] | [] | No |
Graph Attribute Object
Property | Description | Type | Default | Required |
---|---|---|---|---|
attributeid | The Attribute whose values to plot in the graph. See Minimal Attribute Object below. | Object | Yes | |
color | The 6-character hexadecimal color code used to represent the Attribute in the Graph (without the # symbol).Example: 00FF00 |
String | Yes | |
drawtype | The line style for XY Line charts.
|
Number | 0 |
Yes |
sortorder | The order in which to display the set of Graph Attribute objects on the Graph. | Number | 0 |
Yes |
type | Deprecated field | Number | 0 |
Yes |
Marker Object
Property | Description | Type | Default | Required |
---|---|---|---|---|
attributeid | The Attribute whose values to plot in the graph. See Minimal Attribute Object below. | Object | Yes | |
color | The 6-character hexadecimal color code used to represent the Annotation Marker in the Graph (without the # symbol).Example: 00FF00 |
String | Yes | |
label | The text to display on the Annotation Marker. | String | null |
Recommended |
value | The value on which to place the Annotation Marker. | Number | null |
Recommended |
Minimal Attribute Object
Property | Description | Type | Required |
---|---|---|---|
edge_device | The name of the Edge Device which contains the CI that owns the Attribute being plotted. | String | Yes |
ci | The name of the CI which owns the Attribute being plotted. | String | Yes |
attribute | The name of the Attribute being plotted. | String | Yes |
Delete
To delete a Graph, send a DELETE request using the same query parameters as the Direct Fetch request.