Working with Groups

Summary

/api/v1/groups /api/v1/groups/{id} /api/v1/groups/{id}/status

GET /api/v1/groups

List all Element groups visible to the user account, as well as each Element groups' member Elements and monitors.

Returned Fields

For each returned Element group, the following fields are provided:

Field	Type	Description
description	String	description of this Element group
elements	Array	an array listing the Elements that belong to this Element group (see Elements Array below for details)
groupId	Integer	ID for this Element group's parent group; can return a null value for the top-level group
id	Integer	ID for this Element group
monitors	Array	an array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
name	String	the name of this Element group

Elements Array

The following fields are provided for each Element belonging directly to an Element group:

Field	Type	Description
id	Integer	ID for the child Element
isMonitored	Boolean	monitoring status for the child Element
name	String	display name for the child Element

Monitors Array

The following fields are provided for each service monitor belonging to Elements that belong to this Element group:

Field	Type	Description
elementId	Integer	ID of the Element this child service monitor is related to; can be null for unassigned monitors
id	Integer	ID for the child service monitor
isHidden	Boolean	hidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the child service monitor
name	String	name of the child service monitor

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1012	Element Group Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015	Invalid Element Group Filter	400	The Element filter you are referencing does not exist.

Example

List all Element groups visible to the user:

GET https://youruptime/api/v1/groups/

[
   {
      "description": "Collects basic performance data",
      "elements": 
      [
         {
            "id": 1,
            "isMonitored": true,
            "name": "win-dleith"
         },
         {
            "id": 2,
            "isMonitored": true,
            "name": "rd-vc2"
          }
      ],
      "groupId": null,
      "id": 1,
      "monitors":
      [
         {
            "elementId": 1,
            "id": 2,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-localhost"
         },
         ...
      ],
      "name": "My Infrastructure",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 2,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Virtual Machines",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 3,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Hosts",
   },
   ...
]

GET /api/v1/groups/{id}

List a specific Element group's member Elements and monitors.

Returned Fields

The following fields are provided:

Field	Type	Description
description	String	description of this Element group
elements	Array	an array listing the Elements that belong to this Element group (see Elements Array below for details)
groupId	Integer	ID for this Element group's parent group; can return a null value for the top-level group
id	Integer	ID for this Element group
monitors	Array	an array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
name	String	the name of this Element group

Elements Array

The following fields are provided for each Element belonging directly to an Element group:

Field	Type	Description
id	Integer	ID for the child Element
isMonitored	Boolean	monitoring status for the child Element
name	String	display name for the child Element

Monitors Array

The following fields are provided for each service monitor belonging to Elements that belong to this Element group:

Field	Type	Description
elementId	Integer	ID of the Element this child service monitor is related to; can be null for unassigned monitors
id	Integer	ID for the child service monitor
isHidden	Boolean	hidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the child service monitor
name	String	name of the child service monitor

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1002	Element Group Does Not Exist	404	A specifically referenced Element group does not exist. In such a case, referencing `https://youruptime:9997/api/` `v1/groups/789/` would return the following: `The element group id '789' does not exist.`
UT-1012	Element Group Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015	Invalid Element Group Filter	400	The Element filter you are referencing does not exist.
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.

Example

List the contents of Element group ID 1:

GET https://youruptime/api/v1/groups/1

[
   {
      "description": "Collects basic performance data",
      "elements": 
      [
         {
            "id": 1,
            "isMonitored": true,
            "name": "win-dleith"
         },
         {
            "id": 2,
            "isMonitored": true,
            "name": "rd-vc2"
          }
      ],
      "groupId": null,
      "id": 1,
      "monitors":
      [
         {
            "elementId": 1,
            "id": 2,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-localhost"
         },
         ...
      ],
      "name": "My Infrastructure",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 2,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Virtual Machines",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 3,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Hosts",
   },
   ...
]

GET /api/v1/groups/{id}/status

Display the status of an Element group's member Elements and monitors.

Returned Fields

The following fields are provided for the returned Element group:

Field	Type	Description
elementStatus	Array	an object listing the status of the parent Element for this monitor (see Element Status Array below for details)
id	Integer	ID for this service monitor
monitorStatus	Array	the output message produced the last time the service monitor was executed (see Monitor Status Array below for details)
name	String	name of this service monitor
topologyParentStatus	Array	last known status of this service monitor (see Topology Status Array below for details)

Element Status Array

The following fields are provided for each Element in the Element group:

Field	Type	Description
id	Integer	ID of the child Element
isMonitored	Boolean	monitoring status for the child Element
name	String	display name of the child Element
message	String	the output message produced the last time the child Element changed status
status	String	last known status of the child Element
lastCheckTime	String - Date Time	the last time the child Element's status was successfully checked
lastTransitionTime	String - Date Time	last time the child Element changed status, which can be used to determine time in its current status
powerState	String	the current power state of the child Element (only provided for virtual Elements; all other Elements will return null)

Monitor Status Array

The following fields are provided for each service monitor associated with Elements in the Element group:

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 Uptime Infrastructure Monitor uses, and can generally be ignored
isHostCheck	Boolean	returns true if this service monitor is the host check for its parent Element
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor
message	String	output message produced the last time the service monitor was executed
status	String	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, which can be used to determine time at its current status

Topology Status Array

The topologyParentStatus array can be used to map topological dependency failures using identified parent child Element relationships:

Field	Type	Description
id	Integer	ID for this service monitor
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, which can be used to determine time at its current status
message	String	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	last known status of the parent Element

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1002	Element Group Does Not Exist	404	A specifically referenced Element group does not exist. In such a case, referencing `https://youruptime:9997/api/` `v1/groups/789/` would return the following: `The element group id '789' does not exist.`
UT-1012	Element Group Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015	Invalid Element Group Filter	400	The Element filter you are referencing does not exist.
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.

Example

Retrieve status for Element group ID 1 (by default, the My Infrastructure group):

GET https://youruptime/api/v1/groups/1/status

{
   "elementStatus": 
   [
      {
         "id": 1,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "win-dleith",
         "powerState": "On",
         "status": "OK"
      },
      ...
   ]
   "id": 1,
   "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"
      },
      ...
   ]
   "name": "My Infrastructure",
   "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"
      },
      ...
   ]
}

Page tree

Working with Groups

Summary

GET /api/v1/groups

Returned Fields

Elements Array

Monitors Array

Response Codes

Example

GET /api/v1/groups/{id}

Returned Fields

Elements Array

Monitors Array

Response Codes

Example

GET /api/v1/groups/{id}/status

Returned Fields

Element Status Array

Monitor Status Array

Topology Status Array

Response Codes

Example