The following describes all actions that can be executed with or on up.time Elements.
List Elements visible to the authenticated user account.
To list all Elements:
GET https://youruptime/api/v1/elements/
To list a specific Element:
GET https://youruptime/api/v1/elements/<id>/
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"
} |
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. |
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 |
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 |
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 |
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 |
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.)
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"
}
]
} |
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 |
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 |
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 |
| 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 |
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": []
} |