...
Section | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
...
Anchor | ||||
---|---|---|---|---|
|
...
List all visible Elements:
GET https://youruptime/api/v1/elements
Code Block |
---|
[ { "description": "QA Windows 2008 64bit", "groupId": 1, "hostname": "qa-w2k8-x64", "id": 1, "isMonitored": true, "monitors": [ { "elementId": 1, "id": 55, "isHidden": true, "isMonitored": true, "name": "Configuration Update Gatherer" }, { "elementId": 1, "id": 54, "isHidden": true, "isMonitored": true, "name": "Platform Performance Gatherer" }, { "elementId": 1, "id": 52, "isHidden": false, "isMonitored": true, "name": "PING-qa-w2k8-x64" }, { "elementId": 1, "id": 53, "isHidden": false, "isMonitored": true, "name": "UPTIME-qa-w2k8-x64" } ], "name": "qa-w2k8-x64", "tags": [ ], "topologicalChildren": [ ], "topologicalParents": [ ], "type": "Server", "typeName": "Server", "typeOs": "Windows Vista/Server 2008", "typeSubtype": "Windows", "typeSubtypeName": "Microsoft Windows" }, ... { "description": null, "groupId": 1, "hostname": "vmh-rd7", "id": 8, "isMonitored": true, "monitors": [ { "elementId": 8, "id": 180, "isHidden": true, "isMonitored": true, "name": "Advanced Platform Performance Gatherer" }, { "elementId": 8, "id": 24, "isHidden": false, "isMonitored": true, "name": "PING-vmh-rd7" }, { "elementId": 8, "id": 23, "isHidden": true, "isMonitored": true, "name": "Platform Performance Gatherer" }, { "elementId": 8, "id": 179, "isHidden": true, "isMonitored": true, "name": "vSphere ESX Server Configuration Gatherer" } ], "name": "VMH RD7", "tags": [ ], "topologicalChildren": [ ], "topologicalParents": [ { "id": 48, "isMonitored": true, "name": "VC4" } ], "type": "Server", "typeName": "Server", "typeOs": "VMware ESXi 5.1.0 build-1312873", "typeSubtype": "VcenterHostSystem", "typeSubtypeName": "VMware vSphere Server" }, ... { "description": "VMware vCenter Server", "groupId": 1, "hostname": "rd-vc4", "id": 48, "isMonitored": true, "monitors": [ { "elementId": 48, "id": 168, "isHidden": true, "isMonitored": true, "name": "Configuration Update Gatherer" }, { "elementId": 48, "id": 167, "isHidden": true, "isMonitored": true, "name": "vCenter Health Check Monitor" }, { "elementId": 48, "id": 166, "isHidden": true, "isMonitored": true, "name": "Storage Data Gatherer" }, { "elementId": 48, "id": 165, "isHidden": true, "isMonitored": true, "name": "Platform Performance Gatherer" } ], "name": "VC4", "tags": [ ], "topologicalChildren": [ { "id": 12, "isMonitored": true, "name": "VMH RD15" }, { "id": 6, "isMonitored": true, "name": "VMH RD13" }, ... { "id": 8, "isMonitored": true, "name": "VMH RD7" }, { "id": 5, "isMonitored": true, "name": "VMH RD12" }, { "id": 4, "isMonitored": true, "name": "VMH RD6" } ], "topologicalParents": [ ], "type": "Server", "typeName": "Server", "typeOs": "VMware vCenter Server 5.1.0 build-1364037", "typeSubtype": "VcenterServer", "typeSubtypeName": "VMware vCenter Server" }, ... ] |
...
List a specific Element (for example, ID #16):
GET https://youruptime/api/v1/elements/16
Code Block |
---|
{ "description": "QA Windows 2008 64bit", "groupId": 1, "hostname": "qa-w2k8-x64", "id": 16, "isMonitored": true, "monitors": [ { "elementId": 16, "id": 54, "isHidden": true, "isMonitored": true, "name": "Platform Performance Gatherer" }, { "elementId": 16, "id": 53, "isHidden": false, "isMonitored": true, "name": "UPTIME-qa-w2k8-x64" }, { "elementId": 16, "id": 52, "isHidden": false, "isMonitored": true, "name": "PING-qa-w2k8-x64" }, { "elementId": 16, "id": 55, "isHidden": true, "isMonitored": true, "name": "Configuration Update Gatherer" } ], "name": "qa-w2k8-x64", "tags": [ ], "topologicalChildren": [ ], "topologicalParents": [ ], "type": "Server", "typeName": "Server", "typeOs": "Windows Vista/Server 2008", "typeSubtype": "Windows", "typeSubtypeName": "Microsoft Windows" } |
...
To determine the status of an Element's topological parent, refer to the Element listing's topologicalParents
array. Consider the following example:
GET https://youruptime/api/v1/elements/42
The response indicates this Element's parent, RDBuilds
, has an ID of 40:
...
Use the status
task on the Element (in this case, ID=40) to retrieve its status:
GET
https://youruptime/api/
v1/elements/40/status
Code Block |
---|
{ "id": 40, "isMonitored": true, "lastCheckTime": "2016-01-15T09:07:45", "lastTransitionTime": "2016-01-14T22:22:05", "message": "", "monitorStatus": [ { "acknowledgedComment": null, "elementId": 40, "id": 133, "isAcknowledged": false, "isHidden": false, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2016-01-15T09:08:58", "lastTransitionTime": "2016-01-14T22:18:18", "message": "uptime agent running on RDBuilds, uptime agent 5.3.0 (build 3) linux", "name": "UPTIME-RDBbuilds", "status": "OK" }, { "acknowledgedComment": null, "elementId": 40, "id": 135, "isAcknowledged": false, "isHidden": true, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2016-01-15T09:08:25", "lastTransitionTime": "2016-01-14T22:22:45", "message": "Information received from Agent: uptime agent 5.3.0 (build 3) linux ", "name": "Platform Performance Gatherer", "status": "OK" }, { "acknowledgedComment": null, "elementId": 40, "id": 134, "isAcknowledged": false, "isHidden": false, "isHostCheck": true, "isMonitored": true, "lastCheckTime": "2016-01-15T09:07:45", "lastTransitionTime": "2016-01-14T22:22:05", "message": "Ping completed: 5 sent, 0.0% loss, 0.4ms average round trip time", "name": "PING-RDBuilds", "status": "OK" }, { "acknowledgedComment": null, "elementId": 40, "id": 136, "isAcknowledged": false, "isHidden": true, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2016-01-15T03:45:01", "lastTransitionTime": "2016-01-15T03:45:01", "message": "Information received from Agent: uptime agent 5.3.0 (build 3) linux ", "name": "Configuration Update Gatherer", "status": "OK" } ], "name": "RDBuilds", "powerState": null, "status": "OK", "topologyParentStatus": [] } |
...
Produces basic availability information, similar to the status shown on Global Scan. Using the standard API format, the status
task can only be called against one Element at a time, based on ID:
GET https://youruptime/api/v1/elements/<id>/status
Multiple Elements can first be filtered before calling by a status
task. (See Filtering Objects for more information.)
...
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
OK | 200 | Information retrieved successfully. | |
UT-1000 | Element Does Not Exist | 404 | A specifically referenced Element ID does not exist. In such a case, referencing
The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor. |
UT-1010 | Element Filter Expired | 410 | The filter you are referencing is expired. Created filters persist, by default, for five minutes. |
UT-1012 | Element Group Filter Expired | 410 | The group filter you are referencing is expired. Created filters persist, by default, for five minutes. |
UT-1013 | Invalid Element Filter | 400 | The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON. |
UT-1015 | Invalid Element Group Filter | 400 | The JSON used to create an Element group filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON. |
UT-1028 | URL ID Body Mismatch | 400 | The Element ID in the URL and the JSON object do not match. |
Example
GET https://youruptime/api/v1/elements/1/status
Code Block |
---|
{ "id": 1, "isMonitored": true, "lastCheckTime": "2016-09-17T14:13:56", "lastTransitionTime": "2016-09-13T11:34:38", "message": "", "monitorStatus": [ { "elementId": 1, "id": 7, "isHidden": false, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2016-09-17T14:13:56", "lastTransitionTime": "2016-09-17T14:05:56", "message": "", "name": "Default File System Capacity", "status": "UNKNOWN" }, { "elementId": 1, "id": 8, "isHidden": false, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2016-09-17T14:13:56", "lastTransitionTime": "2016-09-17T14:13:56", "message": "", "name": "Default Agent Service Check", "status": "UNKNOWN" }, ... ], "name": "win-dleith", "powerState": "On", "status": "OK", "topologyParentStatus": [ { "id": 2, "isMonitored": true, "lastCheckTime": "2016-09-17T14:14:17", "lastTransitionTime": "2016-09-13T11:34:24", "message": "", "name": "rd-vc2", "powerState": null, "status": "OK" }, { "id": 15, "isMonitored": true, "lastCheckTime": "2016-09-17T14:09:33", "lastTransitionTime": "2016-09-13T11:34:32", "message": "", "name": "vmh-rd6.rd.local", "powerState": "On", "status": "OK" } ] } |
...
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
UT-0200 | OK | 200 | Operation performed successfully. |
UT-1000 | Element Does Not Exist | 404 | A specifically referenced Element ID does not exist. In such a case, referencing
The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor. |
UT-1002 | Element Group Does Not Exist | 400 | The referenced group ID does not exist. |
UT-1025 | Invalid Request Body JSON | 400 | The JSON object is not well formed. |
UT-1028 | URL ID Body Mismatch | 400 | The Element ID in the URL and the JSON object do not match. |
UT-1029 | Duplicate Hostname | 200 | Another Element (which you may not have permission to view) already exists with this hostname. |
UT-1030 | Duplicate Element Name | 200 | Another Element (which you may not have permission to view) already exists with this display name. |
UT-1033 | License Violation | 400 | Setting this Element to isMonitored exceeds the current license. |
UT-1040 | Spaces in Hostname | n/a | The Element hostname cannot contain whitespace. |
UT-1041 | Proxy Error | 400 | This error can occur when your deployment includes a UI instance. |
UT-1042 | HMC Violation | 400 | This error can occur when updating a pSeries-based Element that uses the HMC. |
UT-1043 | Missing Field | n/a (JSON validation) | One or more of the Element ID, name, or hostname is missing. |
UT-1044 | Field Number out of Range | n/a | The declared Element group ID needs to be equal to or greater than 1. |
UT-1045 | Field Too Long | n/a | One or more of the Element's name, description, or hostname exceed the maximum number of characters. |
...
Change the display name, description, and hostname of an Element (for example, ID #3):
PUT https://youruptime/api/v1/elements/3
Code Block |
---|
{ "id": 3, "name": "pserv2", "description": "print server new location", "hostname": "10.1.1.100" } |
Disable monitoring for the same Element:
PUT https://youruptime/api/v1/elements/3
Code Block |
---|
{ "id": 3, "isMonitored": false } |
Move the Element from the default Infrastructure (with a groupId
of 1
) to another group:
PUT https://youruptime/api/v1/elements/3
Code Block |
---|
{ "id": 3, "groupId": 2 } |
...
Code Block |
---|
POST https://youruptime/api/v1/elements { "name": "Win7 agentless/WMI", "description": "Windows 7 Production", "hostname": "Win7-Production", "groupId": 1, "type": "Server", "collectionMethod": { "connectionType": "wmi", "useGlobalConnectionSettings": false, "wmiDomain": "windomain", "wmiUsername": "administrator", "wmiPassword": "password" } } |
...
Anchor |
---|
...
|
...
|
...
Hyper-V Server)
JSON Request
The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:
Field | Description | Requirements | |||
---|---|---|---|---|---|
name | display name for the Element anywhere in the Uptime Infrastructure Monitor Web interface |
| |||
description | optional description for the Element |
| |||
hostname | resolvable network hostname or IP address of the Element |
| |||
groupid | the Element Group the Element is placed in upon creation |
| |||
type | the basic Element type:
|
| |||
collectionMethod | array of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element |
| |||
connectionType | the connection method for the Element:
| snmp
|
| Element
|
|
useGlobalConnectionSettings | Boolean determining whether the Uptime Infrastructure Monitor Agent Global SNMP Configuration Settings are set is enabled in Global Credentials Element Settings if true, all other connection properties are ignored |
| |||
hypervDomain | the Windows domain in which WMI is implemented | snmpVersion |
| ||
hypervUsername | the name of the account with access to WMI on the Windows domain | snmpPort | the port on which the device is listening
| ||
hypervPassword | the password for the username above the plaint-text password is passed to Uptime Infrastructure Monitor using an encrypted connection |
|
Response Codes
The following common response codes may result from this operation:
Include Page | ||||
---|---|---|---|---|
|
Other response codes that may occur include the following:
Error Code | Error | HTTP Code | Details |
---|---|---|---|
OK | 200 | Operation performed successfully. | |
UT-1025 | Invalid Request Body JSON | 400 | The JSON object is not well formed. |
UT-1029 | Duplicate Hostname | 400 | Another Element (which you may not have permission to view) already exists with this hostname. |
UT-1030 | Duplicate Element Name | 400 | Another Element (which you may not have permission to view) already exists with this display name. |
UT-1033 | License Violation | 400 | Adding this Element exceeds the current license. |
UT-1035 | Add Element Error | 400 | An exception occurred when trying to add the Element. Could not add Hyper-V Server: This server has already been added. |
UT-1040 | Spaces in Hostname | n/a (JSON validation) | The Element hostname cannot contain whitespace. |
UT-1043 | Missing Field | n/a (JSON validation) | One or more of the Element ID, name, hostname, or group ID is missing. |
UT-1044 | Field Number out of Range | n/a (JSON validation) | The declared Element group ID needs to be equal to or greater than 1. |
UT-1045 | Field Too Long | n/a (JSON validation) | One or more of the Element's name, description, or hostname exceeds the maximum number of characters. |
UT-1034 | WMI Not Supported | 400 | You are most likely trying to add a WMI-based Element to a non-Windows host. |
Example
Add a Hyper-V server whose metrics are reported via WMI:
Code Block |
---|
POST https://youruptime/api/v1/elements
{
"name": "Win 7 Hyper-V Host Server",
"description": "Windows 7 Production",
"hostname": "Win7-Production",
"groupId": 1,
"type": "Server",
"collectionMethod": {
"connectionType": "hyperv",
"useGlobalConnectionSettings": false,
"hypervDomain": "windomain",
"hypervUsername": "administrator",
"hypervPassword": "password",
}
} |
After the Hyper-V Host is successfully added, please perform following steps:
- Navigate to Infrastructure page.
- View the newly added Hyper-V Host Server.
- Edit the Sync settings to turn on Collect Virtual Machine data.
- Uptime will start collecting Guest VMs data.
Info |
---|
All the existing service requests detailed out in this topic will work for Hyper-V with the addition of newly created, above mentioned POST service request. |
...
Anchor | ||||
---|---|---|---|---|
|
JSON Request
The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:
Field | Description | Requirements | ||
---|---|---|---|---|
name | display name for the Element anywhere in the Uptime Infrastructure Monitor Web interface |
| ||
description | optional description for the Element |
| ||
hostname | resolvable network hostname or IP address of the Element |
| ||
groupId | the Element Group the Element is placed in upon creation |
| ||
type | the basic Element type:
|
| ||
collectionMethod | array of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element |
| ||
connectionType | the connection method for the Element:
|
| ||
useGlobalConnectionSettings | Boolean determining whether Global SNMP Configuration Settings are set in Global Credentials Settings if |
| ||
snmpVersion | the SNMP version used to connect to the network device:
|
| ||
snmpPort | the port on which the device is listening |
| ||
snmpV2ReadCommunity | the SNMP | snmpV2ReadCommunity | the SNMP community to use for the connection, typically set to public |
|
isPingable | determines whether Uptime Infrastructure Monitor can contact the device using the ping utility |
|
Response Codes
The following common response codes may result from this operation:
...
Other response codes that may occur include the following:
Error Code | Error | HTTP Code | Details |
---|---|---|---|
OK | 200 | Operation performed successfully. | |
UT-1025 | Invalid Request Body JSON | 400 | The JSON object is not well formed. |
UT-1029 | Duplicate Hostname | 400 | Another Element (which you may not have permission to view) already exists with this hostname. |
UT-1030 | Duplicate Element Name | 400 | Another Element (which you may not have permission to view) already exists with this display name. |
UT-1033 | License Violation | 400 | Adding this Element exceeds the current license. |
UT-1035 | Add Element Error | 400 | An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct. |
UT-1040 | Spaces in Hostname | n/a | The Element hostname cannot contain whitespace. |
UT-1043 | Missing Field | n/a (JSON validation) | One or more of the Element ID, name, hostname, or group ID is missing. |
UT-1044 | Field Number out of Range | n/a | The declared Element group ID needs to be equal to or greater than 1. |
UT-1045 | Field Too Long | n/a | One or more of the Element's name, description, or hostname exceed the maximum number of characters. |
Example
Add an SNMP v2 network device:
...
Field | Description | Requirements | ||
---|---|---|---|---|
name | display name for the Element anywhere in the Uptime Infrastructure Monitor Web interface |
| ||
description | optional description for the Element |
| ||
hostname | resolvable network hostname or IP address of the Element |
| ||
groupId | the Element Group the Element is placed in upon creation |
| ||
type | the basic Element type:
|
| ||
collectionMethod | array of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element |
| ||
connectionType | the connection method for the Element:
|
| ||
useGlobalConnectionSettings | Boolean determining whether Global SNMP Configuration Settings are set in Global Credentials Settings if |
| ||
snmpVersion | the SNMP version used to connect to the network device:
|
| ||
snmpPort | the port on which the device is listening |
| ||
snmpV3Username | the name required to connect to the network device |
| ||
snmpV3AuthenticationPassword | the password required to connect to the network device
|
| ||
snmpV3AuthenticationMethod | determines how encrypted data moving between the network device and Uptime Infrastructure Monitor is authenticated:
|
| ||
snmpV3PrivacyPassword | the password used to encrypt data moving between the network device and Uptime Infrastructure Monitor
|
| ||
snmpV3PrivacyType | determines how data moving between the network device and Uptime Infrastructure Monitor is encrypted:
|
| ||
isPingable | determines whether Uptime Infrastructure Monitor can contact the device using the ping utility |
|
Response Codes
The following common response codes may result from this operation:
...
Error Code | Error | HTTP Code | Details |
---|---|---|---|
OK | 200 | Operation performed successfully. | |
UT-1025 | Invalid Request Body JSON | 400 | The JSON object is not well formed. |
UT-1029 | Duplicate Hostname | 400 | Another Element (which you may not have permission to view) already exists with this hostname. |
UT-1030 | Duplicate Element Name | 400 | Another Element (which you may not have permission to view) already exists with this display name. |
UT-1033 | License Violation | 400 | Adding this Element exceeds the current license. |
UT-1035 | Add Element Error | 400 | An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct. |
UT-1040 | Spaces in Hostname | n/a | The Element hostname cannot contain whitespace. |
UT-1043 | Missing Field | n/a (JSON validation) | One or more of the Element ID, name, hostname, or group ID is missing. |
UT-1044 | Field Number out of Range | n/a | The declared Element group ID needs to be equal to or greater than 1. |
UT-1045 | Field Too Long | n/a | One or more of the Element's name, description, or hostname exceed the maximum number of characters. |
Example
Add an SNMP v3 network device:
...
- deleting a monitored VM through the API marks it as ignored
- deleting an ignored VM through the API returns an error
- deleting an ESX host that is part of a cluster returns an error
Response Codes
The following common response codes may result from this operation:
...
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
No Content | 204 | Operation performed successfully. | |
UT-1000 | Element Does Not Exist | 404 | A specifically referenced Element ID does not exist. In such a case, referencing
The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor. |
UT-1025 | Invalid Request Body JSON | 400 | The JSON object is not well formed. |
UT-1026 | VM Not Deleted | 403 | VMs and ESX hosts that are ignored cannot be deleted. |
UT-1027 | Element Not Deleted | 403 | You are trying to delete an ESX host that is part of a cluster. |
UT-1032 | Manual Monitor Not Deleted | 403 | Manually monitored hosts cannot be deleted. |
Example
Delete a specific Element (for example, ID #16):
DELETE https://youruptime/api/v1/elements/16
Server