The following describes all actions that can be executed with or on up.time Elements.
Managing Elements
Listing Elements
List Elements visible to the authenticated user account.
Endpoint
To list all Elements:
GET https://youruptime/api/v1/elements/
To list a specific Element:
GET https://youruptime/api/v1/elements/<id>/
Example Requests and Responses
List all visible Elements:
GET https://youruptime/api/v1/elements
[
{
"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 (e.g., ID #16):
GET https://youruptime/api/v1/elements/16
{
"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"
}
Response Field Details
For each returned Element the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| description | String | Description of this Element. |
| groupId | Integer | ID for this Elements' parent Element group. |
| hostname | String | Hostname used to contact this Element. |
| id | Integer | ID for this Element. |
| isMonitored | Boolean | Monitoring status for this Element. |
| monitors | Array | An array listing all monitors that belong to this Element (see Monitors Array below for details). |
| name | String | The display name of this Element. |
| tags | Array | An array listing all views/tags that this Element belongs to (see Tags Array below for details). |
| topologicalChildren | Array | An array listing all Elements that are a topological dependency of this Element in up.time (see Topological Children Array below for details). |
| topologicalParents | Array | An array listing all Elements that are topological parents of this Element in up.time (see Topological Parents Array below for details). |
| typeName | String | A basic type definition for the Element. The following types are supported:
|
| typeOs | String | Returns basic operating system information for this Element:
Elements of other types are not currently supported by the API. |
| typeSubtype | String | Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported:
|
| typeSubtypeName | String | Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes. |
Monitors Array
The monitors array is the same across all end points. For each monitor associated with this Element the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| elementId | Integer | ID of the Element this monitor is related to |
| id | Integer | ID of the service monitor |
| isHidden | Boolean | hidden monitors are internal monitors that up.time uses, and can generally be ignored |
| isMonitored | Boolean | monitoring status for the service monitor |
| name | String | name of the service monitor |
Tags Array
For each tag or view associated with this Element, the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| id | Integer | ID of the tag or view |
| name | String | name of the tag or view |
Topological Children Array
For each Element that is topologically dependent on this Element, the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| id | Integer | ID of the tag or view |
| isMonitored | Boolean | monitoring status for the Element |
| name | String | name of the tag or view |
Topological Parents Array
For each Element on which this Element is topologically dependent, the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| id | Integer | ID of the tag or view |
| isMonitored | Boolean | monitoring status for the Element |
| name | String | name of the tag or view |
Actions On An Element
View Element Status Summary
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 being called by a status task. (See Filtering Objects for more information.)
Example Response
GET https://youruptime/api/v1/elements/1/status
{
"id": 1,
"isMonitored": true,
"lastCheckTime": "2012-09-17T14:13:56",
"lastTransitionTime": "2012-09-13T11:34:38",
"message": "",
"monitorStatus":
[
{
"elementId": 1,
"id": 7,
"isHidden": false,
"isHostCheck": false,
"isMonitored": true,
"lastCheckTime": "2012-09-17T14:13:56",
"lastTransitionTime": "2012-09-17T14:05:56",
"message": "",
"name": "Default File System Capacity",
"status": "UNKNOWN"
},
{
"elementId": 1,
"id": 8,
"isHidden": false,
"isHostCheck": false,
"isMonitored": true,
"lastCheckTime": "2012-09-17T14:13:56",
"lastTransitionTime": "2012-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": "2012-09-17T14:14:17",
"lastTransitionTime": "2012-09-13T11:34:24",
"message": "",
"name": "rd-vc2",
"powerState": null,
"status": "OK"
},
{
"id": 15,
"isMonitored": true,
"lastCheckTime": "2012-09-17T14:09:33",
"lastTransitionTime": "2012-09-13T11:34:32",
"message": "",
"name": "vmh-rd6.rd.local",
"powerState": "On",
"status": "OK"
}
]
}
Response Field Details
For the returned Element the following fields will be provided:
| Field | Type | Description |
|---|---|---|
| id | Integer | ID for this service monitor |
| isMonitored | Boolean | monitoring status for this service monitor |
| lastCheckTime | String - Date Time | the last time this service monitor was executed successfully |
| lastTransitionTime | String - Date Time | the last time this service monitor changed status; this field can be used to determine time in the current status |
| message | String | the output message produced the last time the service monitor was executed |
| name | String | display name of this Element |
| powerState | String | the current power state of the Element (only provided for virtual Elements; all other Elements will return null) |
| status | String | the last known status of this Element |
| monitorStatus | Array | an array listing the status of all monitors related to this Element (see Monitor Status Arrays below for more detail) |
| topologyParentStatus | Array | an array listing the status of all topological parent Elements that this Element is a child to (see Topology Status Arrays for more detail) Note: this field has been deprecated |
| masterMonitorsStatus | Array | an array listing the status of all master service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail) |
| memberMonitorStatus | Array | an array listing the status of all member service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail |
Monitor Status Arrays
The monitorStatus, masterMonitorStatus, and memberMonitorStatus arrays all provide the same response fields for each service monitor listed in the array:
| Field | Type | Description |
|---|---|---|
| elementId | Integer | ID of the Element this monitor is related to |
| id | Integer | ID of the service monitor |
| isHidden | Boolean | hidden monitors are internal monitors that up.time uses, and can generally be ignored |
| isMonitored | Boolean | monitoring status for the service monitor |
| name | String | name of the service monitor |
| message | String | the output message produced the last time the service monitor was executed |
| status | String | the last known status of this service monitor |
| lastCheckTime | String - Date Time | the last time this service monitor was executed successfully |
| lastTransitionTime | String - Date Time | the last time this service monitor changed status; this field can be used to determine time in the current status |
Topology Status Arrays
The topologyParentStatus array can be used to map topological dependency failures using identified parent child Element relationships.
Note: This field has been deprecated. You should instead use the topologicalChildren and topologicalParents arrays in an Element's specific listing.
| Field | Type | Description |
|---|---|---|
| id | Integer | ID for the parent Element |
| isMonitored | Boolean | monitoring status for the parent Element |
| lastCheckTime | String - Date Time | the last time the parent Element was checked successfully |
| lastTransitionTime | String - Date Time | the last time this parent Element changed status; this field can be used to determine time in the current status |
| message | String | the output message produced the last time the parent's status changed |
| name | String | display name of the parent Element |
| powerState | String | the current power state of the parent Element (only provided for virtual Elements; all other Elements will return null) |
| status | String | the last known status of the parent Element |
Determining an Element's Topological Parent
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:
{
"description": "uptime agent on production test with ssl (port 5556)",
"groupId": 1,
"hostname": "qa-agent01",
"id": 42,
"isMonitored": true,
"monitors": [
{
"elementId": 42,
"id": 141,
"isHidden": false,
"isMonitored": true,
"name": "PING-qa-agent01"
},
{
"elementId": 42,
"id": 142,
"isHidden": true,
"isMonitored": true,
"name": "Platform Performance Gatherer"
},
{
"elementId": 42,
"id": 144,
"isHidden": true,
"isMonitored": true,
"name": "Configuration Update Gatherer"
},
{
"elementId": 42,
"id": 143,
"isHidden": false,
"isMonitored": true,
"name": "UPTIME-qa-agent01"
}
],
"name": "qa-agent01.rd.local",
"tags": [],
"topologicalChildren": [],
"topologicalParents": [
{
"id": 40,
"isMonitored": true,
"name": "RDBuilds"
}
],
"type": "Server",
"typeName": "Server",
"typeOs": "Red Hat Linux 5.2",
"typeSubtype": "Linux",
"typeSubtypeName": "Linux"
}
Use the status task on the Element (in this case, ID=40) to retrieve its status:
GET https://youruptime/api/v1/elements/40/status
{
"id": 40,
"isMonitored": true,
"lastCheckTime": "2014-01-15T09:07:45",
"lastTransitionTime": "2014-01-14T22:22:05",
"message": "",
"monitorStatus": [
{
"acknowledgedComment": null,
"elementId": 40,
"id": 133,
"isAcknowledged": false,
"isHidden": false,
"isHostCheck": false,
"isMonitored": true,
"lastCheckTime": "2014-01-15T09:08:58",
"lastTransitionTime": "2014-01-14T22:18:18",
"message": "up.time agent running on RDBuilds, up.time 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": "2014-01-15T09:08:25",
"lastTransitionTime": "2014-01-14T22:22:45",
"message": "Information received from Agent: up.time 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": "2014-01-15T09:07:45",
"lastTransitionTime": "2014-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": "2014-01-15T03:45:01",
"lastTransitionTime": "2014-01-15T03:45:01",
"message": "Information received from Agent: up.time agent 5.3.0 (build 3) linux ",
"name": "Configuration Update Gatherer",
"status": "OK"
}
],
"name": "RDBuilds",
"powerState": null,
"status": "OK",
"topologyParentStatus": []
}