SysOrb Network Monitoring System Administrator's Guide: For version 4.6.0
Prev Chapter 14. WebAPI  

14.3. Reference

14.3.1. Authentication

In general, requests that require authentication can be authenticated simply by providing the username, password and domain using Basic HTTP authentication. Since the publicly available protocol is provided only over HTTPS the username/password combination is never transmitted in clear text.

All requests against the WebAPI must be authenticated (either by means of an access token or a real username/password/domain).

14.3.1.1. Method GET /token/

Creates a new valid access token.

User name, password and domain name separated by a single colon (":") should be encoded in Base64 and provided in the 'authorization' header

Example 14-28. Authorization header

authorization: Basic encodeBase64(uname:upass:.)

Reply

If user authenticated successfully return status code 200 Ok and a document with user domain, user id and access token.

Example 14-29. Reply body schema

element authenticated {
 element domain { text }
 & element user { text }
 & element token { text }
}

14.3.1.2. Method DELETE /token/

End session for the user with given token.

Reply

200 OK

14.3.2. Database

14.3.2.1. Domains

14.3.2.1.1. Method GET /domains/[id]

Returns a list of domains under the given domain.

Reply

The reply is a document with the list of domains including object id, version and tree label.

Example 14-30. Reply body schema

element domains {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
 }*
}

14.3.2.1.2. Method GET /domains/[id]/statusinfo

Returns a list of domains under the given domain with their statusInfo objects.

Reply

Example 14-31. Reply body schema

element domains {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
  & element infourl { text }
  & element statusinfo {
  element property {
    element name { text }
    & element value { text }
   }*
  }
 }*
}

14.3.2.1.3. Method GET /domains/[domain_id]/alertlist

Return a list of objects in alert/warning/downtime state.

Reply

Example 14-32. Reply body schema

element alertlist {
  element alerts {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
  & element warnings {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
  & element downtime {
    element domain {
      element id { text }
      & element label { text }
      & element comment { text } ?
      & element infourl { text } ?
      & element node {
        element id { text }
        & element label { text }
        & element comment { text } ?
        & element infourl { text } ?
        & element status { text } ?
        & element check {
          element id { text }
          & element label { text }
          & element comment { text } ?
          & element infourl { text } ?
          & element status { text }
        }*
      }*
    }*
  }
}

14.3.2.1.4. Method GET /domains/[domain_id]/template

Reply

Example 14-33. Reply body schema

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
 }*
}

14.3.2.1.5. Method POST /domains/[id]

Create a domain under the given domain.

Request

Example 14-34. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The URI to the created domain is returned in the location header and version in the content-version header of a successful 201 response.

14.3.2.1.6. Method PUT /domains/[id]

Update properties of a given domain.

Request

Version of the domain to update should be provided in the content-version header of a request.

Example 14-35. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The new version of the updated domain is returned in the content-version header of a successful 200 response.

14.3.2.1.7. Method DELETE /domains/[id]

Delete domain with given id.

Request

Version of the domain should be provided in the content-version header.

Reply

Returns 200 OK on success.

14.3.2.2. Nodes

14.3.2.2.1. Method GET /nodes/[id]

Returns a list of nodes under the given domain.

Reply

Example 14-36. Reply body schema

element nodes {
 element object {
  element class { test }
  & element id { text }
  & element version { text }
  & element treelabel { text }
 }*
}

14.3.2.2.2. Method GET /nodes/[domain_id]/[class_name]

Returns a list of nodes under the given domain with their <class_name> object.

Possible values are: statusinfo, scoreinfo, summary.

Reply

Example 14-37. Reply body schema

element nodes {
  element object {
    element class { test }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element infourl { text }
    & element object {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

14.3.2.2.3. Method GET /nodes/[domain_id]/template

Reply

Example 14-38. Reply body schema

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

14.3.2.2.4. Method POST /nodes/[id]

Create a node under the given domain.

Request

Example 14-39. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The URI to the created node is returned in the location header and version in the content-version header of a successful 201 response.

14.3.2.2.5. Method PUT /nodes/[id]

Update properties of a given node.

Request

Version of the node to update should be provided in the content-version header of a request.

Example 14-40. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The new version of the updated node is returned in the content-version header of a successful 200 response.

14.3.2.2.6. Method DELETE /nodes/[id]

Delete node with given id.

Request

Version of the node should be provided in the content-version header.

Reply

Returns 200 OK on success.

14.3.2.3. Objects

14.3.2.3.1. Method GET /objects/[id]

Returns a list of properties of the given object.

Reply

Example 14-41. Reply body schema

element object {
  element class { text }
  & element id { text }
  & element version { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

14.3.2.3.2. Method GET /objects/[id]/parents

Returns a list of parent objects of the given object beginning from the root.

Reply

Example 14-42. Reply body schema

element parents {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element treelabel { text }
  }*
}

14.3.2.3.3. Method GET /objects/[id]/scoreinfo

Returns a list of properties of the scoreInfo object.

Note: request is applicable for node and check objects.

Reply

Example 14-43. Reply body schema

element scoreinfo {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

14.3.2.3.4. Method GET /objects/[id]/statusinfo

Returns a list of properties of the statusInfo object.

Note: request is applicable for domain and node objects.

Reply

Example 14-44. Reply body schema

element statusinfo {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

14.3.2.3.5. Method GET /objects/[id]/nodesummary

Returns a list of properties of the nodeSummary object.

Note: request is applicable for node objects.

Reply

Example 14-45. Reply body schema

element nodesummary {
  element class { text }
  element property {
    element name { text }
    & element value { text }
  }*
}

14.3.2.4. Checks and CheckGroups

Each node has a tree of CheckGroup and Check objects, and Checks are the leafs of the tree.

To request properties of any object use GET /object/ API call, to navigate through the tree use the following method.

14.3.2.4.1. Method GET /subtree/[id]

Returns a list of children checkgroup/check/check template objects under the given object (node or checkgroup).

Reply

Example 14-46. Reply body schema

element objects {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element treelabel { text }
    & element siblingname { text } ?
    & element active { bool } ?
  }*
}
Note: Optional element <active> valid only for checks, and contain 'true' if check is active.

Note 2: Optional element <siblingName> valid only for check templates.

In case of check template element class will be CheckTemplate.

14.3.2.4.2. Method GET /checks/[check_id]/summary

Returns a properties of checkSummary object of the given check.

Reply

Example 14-47. Reply body schema

element checksummary {
  element class { text }
  & element property {
     element name { text }
     & element value { text }
  }*
}

14.3.2.4.3. Method POST /checks/[check_id]/timeseries

Returns a number of timeseries of a given check for a period of time.

Request

Example 14-48. Request body schema

element timeseries {
  element timestart { timestamp }
  & element timeend { timestamp }
  & element limit { integer }
  & element offset { integer }
}
Reply

Depends on check type.

Example 14-49. Reply body schema for Uptime, Accumulation, Continuous

element timeseries {
  element type { text }
  & element datainterval {
    element timestart { timestamp }
    & element timeend { timestamp }
    & element ngood { integer }
    & element nbad { integer }
    & element min { float }
    & element avg { float }
    & element max { float }
  }*
}

Example 14-50. Reply body schema for Enum

element timeseries {
  element type { text }
  & element datainterval {
    element timestart { timestamp }
    & element timeend { timestamp }
    & element ngood { integer }
    & element nbad { integer }
    & element mask { integer }
  }*
}

Example 14-51. Reply body schema for Incident

element timeseries {
  element type { text }
  & element datainterval {
    element time { timestamp }
    & element severity { integer }
    & element message { text }
  }*
}

14.3.2.4.4. Method GET /checks/[node_id]/[filter]

Returns a list of active checks for a given node, filtered by <filter>

Filter:

filter = "type=" type ["&status=" status]

type = "all" | "netchecks" | "agentchecks" | "snmpchecks" | "esxichecks"

status = "alert" | "warn"

If <status> is not present, return all active checks with checksummary object, otherwise return all active checks with <status> and their scoreinfo objects.

Reply

Example 14-52. Reply body schema

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element checksummary {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}
Example 1

Return all active netchecks for node 1.123456:

GET /checks/1.123456/type=netchecks

Example 14-53. Reply body schema

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element checksummary {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}
Example 2

Return all active netchecks for node 1.123456 that is in the alert status:

GET /checks/1.123456/type=netchecks&status=alert

Example 14-54. Reply body schema

element checks {
  element object {
    element class { text }
    & element id { text }
    & element version { text }
    & element treelabel { text }
    & element group { text }
    & element scoreinfo {
      element class { text }
      & element property {
        element name { text }
        & element value { text }
      }*
    }
  }*
}

14.3.2.4.5. Method GET /checks/[id]/template/<siblingname>

Returns a list of properties that can be filled in order to create/update check.

If parameter <siblingname> is not present, return editable properties of the check.

Otherwise return editable properties of the check template with given siblingName.

Reply

Example 14-55. Reply body schema

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
 }*
}

14.3.2.4.6. Method POST /checks/[id]/template/<siblingname>

Create a new check under given parent id using template <siblingname>.

Valid only for objects of class CheckTemplate (see method GET /subtree)

Request

Example 14-56. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The URI to the created check is returned in the location header and version in the content-version header of a successful 201 response.

14.3.2.4.7. Method PUT /checks/[id]

Update a check with given properties

Request

Version of the check should be provided in the content-version header.

Example 14-57. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The new version of the updated check is returned in the content-version header of a successful 200 response.

14.3.2.4.8. Method DELETE /checks/[id]

Delete the check with given id (for netchecks) or make it inactive (for others).

Request

Version of the check should be provided in the content-version header.

Reply

If the check was made inactive the new version is returned in the content-version header of a successful 202 response.

14.3.2.5. Users

14.3.2.5.1. Method GET /users/[domain_id]

Returns a list of users under the given domain.

Reply

Example 14-58. Reply body schema

element users {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}

14.3.2.5.2. Method GET /users/[domain_id]/template

Reply

Example 14-59. Reply body schema

element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}

14.3.2.5.3. Method POST /users/[domain_id]

Create a new user under given domain.

Request

Example 14-60. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The URI to the created user is returned in the location header and version in the content-version header of a successful 201 response.

14.3.2.5.4. Method PUT /users/[id]

Update a user with given properties

Request

Version of the user should be provided in the content-version header.

Example 14-61. Request body schema

element class { text }
& element property {
  element name { text }
  & element value { text }
}*
Reply

The new version of the updated user is returned in the content-version header of a successful 200 response.

14.3.2.5.5. Method DELETE /users/[id]

Delete the user with given id.

Request

Version of the user should be provided in the content-version header.

Reply

Returns 200 OK on success.

14.3.2.6. Enums

14.3.2.6.1. Method GET /enums/[type]

Returns a list of values for Enumeration of type <type>.

Reply

Example 14-62. Reply body schema

element enum {
 element enumvalue {
  element text { text }
  & element value { uint }
 }*
}









14.3.2.7. Alert
paths




14.3.2.7.1. Method
GET /alertpaths/[user_id]


Returns a list of alertpaths the given user.


Reply




Example 14-63. Reply body schema


element alertpaths {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}







14.3.2.7.2. Method
GET /alertpaths/[user_id]/template


Reply




Example 14-64. Reply body schema


element alertpaths {
                element template {
  element class { text}
  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}*
}







14.3.2.7.3. Method
POST /alertpaths/[user_id]/template/[sibling_name]


Create a new alertpath under the given user.


Request




Example 14-65. Request body schema


element class { text }
& element property {
  element name { text }
  & element value { text }
}*


Reply

The URI to the created alertpath is returned in the location
header and version in the content-version header of a successful
201 response.






14.3.2.7.4. Method
PUT /alertpaths/[id]


Update alertpath with given properties


Request


Version of the alertpath should be provided in the
content-version header.




Example 14-66. Request body schema


element class { text }
& element property {
  element name { text }
  & element value { text }
}*


Reply

The new version of the updated alertpath is returned in the
content-version header of a successful 200 response.






14.3.2.7.5. Method
DELETE /alertpaths/[id]


Delete the alertpath with given id.


Request


Version of the user should be provided in the content-version
header.


Reply


Returns 200 OK on success.








14.3.2.8.
Users




14.3.2.8.1. Method
GET /alertgroups/[domain_id]


Returns a list of alertgroups under the given domain.


Reply




Example 14-67. Reply body schema


element alertgroups {
  element object {
    element class { text }
    & element id { text }
    & element version { text}
    & element name { text }
  }*
}







14.3.2.8.2. Method
GET /alertgroups/[domain_id]/template


Reply




Example 14-68. Reply body schema



                  element alertgroups {
                  element template {
                  element class { text}
                  & element property {
    element name { text }
    & element value { text }
    & element type { text }
  }*
}*
}







14.3.2.8.3. Method
POST /alertgroups/[domain_id]


Create a new alertgroup under given domain.


Request




Example 14-69. Request body schema


element class { text }
& element property {
  element name { text }
  & element value { text }
}*


Reply

The URI to the created alertgroup is returned in the location
header and version in the content-version header of a successful
201 response.






14.3.2.8.4. Method
PUT /alertgroups/[id]


Update a alertgroup with given properties


Request


Version of the alertgroup should be provided in the
content-version header.




Example 14-70. Request body schema


element class { text }
& element property {
  element name { text }
  & element value { text }
}*


Reply

The new version of the updated alertgroup is returned in the
content-version header of a successful 200 response.






14.3.2.8.5. Method
DELETE /alertgroups/[id]


Delete the alertgroup with given id.


Request


Version of the alertgroup should be provided in the
content-version header.


Reply


Returns 200 OK on success.

















Prev
Home
 




Getting Started
Up