RESTful Services

Contents

This page reviews the RESTful API for GroundWork Monitor 7.0.2.

1.0 Auth APIs

(top)

since: 7.0.2

1.1 Login

Authenticates an application, creating an SSO session for the given application. The Login API authenticates an application using three query parameters: user, password and app_name. All of these query parameters are required. Authentication is achieved by calling this API with Base64 encoded credentials in the user and password query parameters. If successful, login returns a simple string: an access token. This token must then be passed to all subsequent Rest API calls in the GWOS-API-TOKEN HTTP header.

Login can return the follow HTTP Response Codes:

200 - Success
400 - Bad Request - if a parameter is missing or badly formed
401 - Unauthorized - failed to login
500 - General server failure
&password=d3N1c2Vy&gwos-app-name=cloudhub

1.1.1 Method: POST

POST /api/auth/login?user=d3N1c2Vy

1.1.2 HTTP Query Parameters

Example

POST /api/auth/login?user=d3N1c2Vy&password=d3N1c2Vy&gwos-app-name=cloudhub
HTTP/1.1 200 OK
Date: Thu, 27 Mar 2014 15:51:56 GMT
Server: Apache-Coyote/1.1
Content-Type: application/xml
Content-Length: 32

24528E5E970AFEC8D1E887DD9CA2C825

1.2 Logout

Logout will end the SSO session for an application. Logout accepts two required query parameters: gwos_api_token, and app_name. If successful, logout returns an HTTP Status Code of 200. Note that the token may already be expired. In this case, the status code will be 404 Not Found, which can effectively be treated the same way as 200.

Login can return the follow HTTP Response Codes:

200 - Success
400 - Bad Request - if a parameter is missing or badly formed
404 - Token not found, can be treated like 200 as the token has already expired
500 - General server failure

1.2.1 Method: POST

POST /api/auth/logout?gwos-api-token=392393939239&gwos-app-name=cloudhub

1.2.2 HTTP Query Parameters

Example

POST /api/auth/logout?gwos-api-token=392393939239&gwos-app-name=cloudhub
HTTP/1.1 200 OK
Date: Thu, 27 Mar 2014 19:13:32 GMT
Server: Apache-Coyote/1.1
Content-Length: 0
Content-Type: text/plain

2.0 Host APIs

(top)

2.1 Query Hosts

Retrieve hosts by query. There are two kinds of queries supported:

1. Retrieving a single host. Retrieves exactly one host object wrapped by an XML <host> element
2. Retrieving one or more hosts. Retrieves 1..n host objects wrapped by an XML <hosts> collection

2.1.1 Method: GET Hosts

GET /api/hosts?query=(query criteria see below)

2.1.2 Method: GET a single host by name

GET /api/hosts/{hostName}

2.1.3 HTTP Query and Path Parameters

If neither a hostName path parameter or query query parameter is not provided, all hosts will be retrieved

2.1.4 HTTP Headers

2.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

Non Queryable Fields

The fields “serviceAvailability” and “bubbleUpStatus” are not queryable since they are calculated fields. However these two fields are calculated and returned in all queries.

For all GET requests, the Hosts Service support three levels of depth:

2.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all hosts, with shallow depth
   GET /api/hosts
2. query for all hosts, with simple depth (only basic attributes, no properties)
   GET /api/hosts?depth=simple
3. query for all hosts, with deep depth
   GET /api/hosts?depth=deep
4. query for a single host named localhost, with depth of shallow
   GET /api/hosts/localhost
5. query for a single host named localhost, with depth of deep
   GET /api/hosts/localhost?depth=deep
6. query for a single host named localhost, with depth of simple
   GET /api/hosts/localhost?depth=simple
7. query on a single property using LIKE operator
   GET /api/hosts?query=property.LastPluginOutput like ‘OK%’
8. query on a property using a range query, and monitor status field, order by a property
   GET /api/hosts?query=(property.ExecutionTime between 10 and 3500 and (monitorStatus <> 'UP')) order by property.ExecutionTime
9. query on host’s lastCheckTime using date functions
   GET /api/hosts?query=day(lastCheckTime) = 22 and month(lastCheckTime) = 5 and minute(lastCheckTime) > 43 order by lastCheckTime
10. query on two numeric properties using range queries, ordering result
    GET /api/hosts?query=(property.ExecutionTime < 10 and property.Latency between 800 and 900) order by property.Latency

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a hostName in the path parameter is always wrapped with a single <host> entity element. Result of queries are always wrapped in a <hosts> collection element, with one or more <host> subelements.

Example Query Results in XML

Here is an XML example of the result of a query finding two hosts at a depth of shallow. Properties are always wrapped in a <properties> collection element. All other fields are attributes.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hosts>
  <host id="1" hostName="localhost" description="localhost" monitorStatus="UP"
    appType="NAGIOS"  deviceIdentification="127.0.0.1"
    lastCheckTime="2013-05-22T09:44:56-07:00"
    bubbleUpStatus="UP" serviceAvailability="9.52" acknowledged="false">
  <properties>
    <property name="MaxAttempts" value="10"/>
    <property name="ExecutionTime" value="6"/>
  </properties>
  <host id="19" hostName="malbec" description="malbec" monitorStatus="UP"
    appType="NAGIOS" deviceIdentification="172.28.113.169"
    lastCheckTime="2013-05-22T09:45:06-07:00"
    bubbleUpStatus="UP" serviceAvailability="0" acknowledged="false">
  </host>
</hosts>

For a single host lookup, the <hosts> wrapper is not presented.

<host id="19" hostName="malbec" description="malbec" monitorStatus="UP"
  appType="NAGIOS" deviceIdentification="172.28.113.169"
  lastCheckTime="2013-05-22T09:45:06-07:00"
  bubbleUpStatus="UP" serviceAvailability="0" acknowledged="false">
</host>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
   Shallow Depth Query Response Data - XML - JSON
   Deep Depth Query Response Data - XML - JSON
   Simple Depth Query Response Data - XML - JSON

2.2 Create Hosts

Post Data AttributCreates a batch (1..n) of new hosts in foundation database. Hosts will be created if they do not exist. If a host exists, it will be updated. Devices will also be created if they do not already exists.

If one or more hosts creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Host creation/update operation is returned back in the resultset described below with a status of success or failure.

2.2.1 Method: POST

POST /api/hosts

2.2.2 HTTP Headers

2.2.3 Request Parameters

2.2.4 Post Data Attributes

2.2.5 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hosts>
  <host hostName="host-100" description="First of my servers"
    monitorStatus="UP" appType="NAGIOS"
    deviceIdentification="192.168.5.50" monitorServer="localhost"
    deviceDisplayName="Device-50" >
    <properties>
      <property name="Latency" value="125" />
    </properties>
  </host>
</hosts>

More Post Data Examples: XML - JSON

2.2.6 HTTP Status Codes

200 - Zero or more hosts were created without any internal server errors
500 - An internal server error occurred

2.2.7 Example Response

In this example, 4 objects were attempted to be created. Only two succeeded, and two failed. The results collection also returns the location of the created or updated host which can be directly used by the GET operation.

<results count='4' success='2' failure='2' entityType=’Host’ operation=’Update’>
  <result status='failure' message='Duplicate hostname already exists' entity='host33' />
  <result status='success' entity='host34'
       location='http://localhost/monitor/api/hosts/host34' />
  <result status='failure' message='Required field Application Type was not provided'
       entity='host35' />
  <result status='success' entity='host36'
       location='http://localhost/monitor/api/hosts/host36' />
</results>

2.3 Delete Host

Deletes one or more hosts from Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more hostnames on URL path
2. Delete with post data, passing in hostnames in post data

2.3.1 Method: DELETE without POST Data

DELETE /api/hosts/hostName

where hostName is a single host name to be deleted

DELETE /api/hosts/hostName1,hostName2
where hostName1,hostName2 is a comma-separated list of hostNames. Note that no-spaces are allowed in this HTTP path segment.

2.3.2 Method: DELETE with POST Data

DELETE /api/hosts

The post data should be formatted like a POST payload, but the only required field is the hostName. Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hosts>
  <host hostName="host-100" />
  <host hostName="host-101" />
</hosts>

JSON, 7.0: (deprecated in 7.1)

[
  { "hostName": "host-100" },
  { "hostName": "host-101" }
]

JSON 7.1:

{ "hosts" : [
  { "hostName": "host-100" },
  { "hostName": "host-101" }
  ]
}

2.3.3 HTTP Headers

2.3.4 HTTP Status Codes

200 - Hosts were deleted successfully
500 - An internal server error occurred

2.3.5 Example Response

<results count='2' success='2' failure='0' entityType=’Host’ operation=’Delete’>
  <result status='success' entity='host-101'
       location='http://localhost/monitor/api/hosts/host-101' />
  <result status='success' entity='localhhost-102'
       location='http://localhost/monitor/api/hosts/102' />
</results>

3.0 Host Group APIs

(top)

3.1 Query Host Groups

Retrieve host groups by query. There are two kinds of queries supported:

1. Retrieving a single host group. Retrieves exactly one host group object wrapped by an XML <hostGroup> element
2. Retrieving one or more host groups . Retrieves 1..n host group objects wrapped by an XML <hostGroups> collection

3.1.1 Method: GET HostGroups

GET /api/hostgroups?query=(query criteria see below)

3.1.2 Method: GET a single host group by name

GET /api/hostgroups/{hostGroupName}

3.1.3 HTTP Query and Path Parameters

If neither a hostGroupName path parameter or query query parameter is not provided, all hosts groups will be retrieved.

3.1.4 HTTP Headers

3.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

3.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all host groups, with shallow depth
   GET /api/hostgroups
2. query for all host groups, with deep depth
   GET /api/hostgroups?depth=deep
3. query for a single host group named Engineering, with depth of shallow
   GET /api/hostgroups/Engineering
4. query for a single host group named Engineering, with depth of deep
   GET /api/hostgroups/Engineering?depth=deep
5. query to find all host groups containing a host named ‘localhost’
   GET /api/hostgroups?query=hosts.hostName = 'localhost'
6. a simple like query on the host group name
   GET /api/hostgroups?query=name like 'Eng%'
7. query for one or more names using in query syntax
   GET /api/hostgroups?query=name in (‘Engineering’,’Support’,’IT’,’HG1’)

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a hostGroupName in the path parameter is always wrapped with a single <hostGroup> entity element. Result of queries are always wrapped in a <hostGroups> collection element, with one or more <hostGroup> subelements.

Here is an XML example of the result of a query finding one host group. Properties are always wrapped in a <properties> collection element. All other fields are attributes.

<hostGroup id="5" name="Support" alias="support" appType="NAGIOS">
  <hosts>
    <host id="17" hostName="mc-cent5-64-a"
    description="mc-cent5-64-a" monitorStatus="UNSCHEDULED DOWN"
    appType="NAGIOS" deviceIdentification="172.28.113.170"
    lastCheckTime="2013-05-22T09:44:16-07:00"
    bubbleUpStatus="UNSCHEDULED DOWN" serviceAvailability="100"
    acknowledged="false" serviceCount="1" />
    <host id="6" hostName="172.28.113.151"
    description="172.28.113.151" monitorStatus="UP"
    appType="NAGIOS" deviceIdentification="172.28.113.151"
    lastCheckTime="2013-05-22T09:43:06-07:00" bubbleUpStatus="UP"
    serviceAvailability="50" acknowledged="false"
    serviceCount="4" />
    <host id="13" hostName="mc-cent5-64-5"
    description="mc-cent5-64-5" monitorStatus="UP"
    appType="NAGIOS" deviceIdentification="172.28.113.161"
    lastCheckTime="2013-05-22T09:45:26-07:00" bubbleUpStatus="UP"
    serviceAvailability="0" acknowledged="false"
    serviceCount="4" />
    <host id="12" hostName="172.28.113.168"
    description="172.28.113.168" monitorStatus="UP"
    appType="NAGIOS" deviceIdentification="172.28.113.168"
    lastCheckTime="2013-05-22T09:43:16-07:00" bubbleUpStatus="UP"
    serviceAvailability="0" acknowledged="false"
    serviceCount="3" />
  </hosts>
</hostGroup>

For queries, the hostGroup elements are wrappered in a hostGroups element.

<hostGroups>
  <hostGroup id="5" name="Support" alias="support" appType="NAGIOS">
    ...
  </hostGroup>
  <hostGroup id="6" name="Sales" alias="sales" appType="NAGIOS">
    ...
  </hostGroup>
  ...
</hostGroups>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Response Data - XML - JSON
  Deep Response Data - XML - JSON

3.2 Create Host Groups

Creates a batch (1..n) of new host groups in foundation database. Host Groups will be created if they do not exist. If a host group exists, it will be updated. You can also specify one or more hosts to be created into the host group. Note these hosts must already exist in the system. They will not be automatically created.

If one or more host groups creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Host Group creation/update operation is returned back in the resultset described below with a status of success or failure.

3.2.1 Method: POST

POST /api/hostgroups

3.2.2 HTTP Headers

3.2.3 Post Data Attributes

3.2.4 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hostGroups>
  <hostGroup name="blueGroup" description="My Blues Group" alias="blue">
    <hosts>
      <host hostName="localhost" />
      <host hostName="notfound-host"/>
    </hosts>
  </hostGroup>
  <hostGroup name="redGroup" description="My Red Group" alias="red">
    <hosts>
      <host hostName="demo"/>
      <host hostName="localhost"/>
    </hosts>
  </hostGroup>
</hostGroups>

More Post Data Examples: XML - JSON

3.2.5 HTTP Status Codes

200 - Zero or more host groups were created without any internal server errors
500 - An internal server error occurred

3.2.6 Example Response

In this example, we use the POST above. Two host group objects were attempted to be created. Additionally, we tried to add two hosts to each host group. One of those hosts "notfound-host" failed to be added to the host group since it didn’t exist in the system. This condition was considered a 'warning' condition.

Note that the results collection also returns the location of the created or updated host group which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="HostGroup" operation="Update" warning="1" count="3">
  <result>
    <entity>blueGroup</entity>
    <location>
    [http://localhost/api/hostgroups/blueGroup]</location>
    <status>success</status>
  </result>
  <result>
    <entity>redGroup</entity>
    <location>
    [http://localhost/api/hostgroups/redGroup]</location>
    <status>success</status>
  </result>
  <result>
    <entity>notfound-host</entity>
    <message>Hosts did not exist and were not processed</message>
    <status>warning</status>
  </result>
</results>

3.3 Delete Host Group

Deletes one or more host groups from the Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more host group names on URL path
2. Delete with post data, passing in host group names in post data

3.3.1 Method: DELETE without POST Data

DELETE /api/hostgroups/hostGroupName

where hostName is a single host group name to be deleted

DELETE /api/hostgroups/hostGroupName1,hostGroupName2
where hostGroupName1,hostGroupName2 is a comma-separated list of host group names. Note that no-spaces are allowed in this HTTP path segment.

3.3.2 Method: DELETE with POST Data

DELETE /api/hostgroups

The post data should be formatted like a POST payload, but the only required field is the host Group name (name). Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hostGroups>
  <hostGroup name="hostGroup-100” />
  <hostGroup name="hostGroup-101” />
</hostGroups>

3.3.3 HTTP Headers

3.3.4 HTTP Status Codes

200 - Hosts were deleted successfully
500 - An internal server error occurred

3.3.5 Example Response

<results count='2' success='2' failure='0' entityType=’HostGroup’ operation=’Delete’>
  <result status='success' entity='hostGroup-100'
    location='http://localhost/monitor/api/hostgroups/hostGroup-100' />
  <result status='success' entity='hostGroup-101'
    location='http://localhost/monitor/api/hostgroups/hostGroup-101' />
</results>

3.4 Clear Host Group

Clears the collection of hosts for one or more host groups from the Collage database. The Clear web service does not actually delete the host group. It simply deletes the associations between a host group and all of its hosts. In effect, ‘clearing’ the host group to an empty set of hosts. Note that the Clear operation uses the DELETE HTTP method and one query parameter named ‘clear’.

There are two methods of clearing:

1. Clear without post data, passing in one or more host group names on URL path
2. Clear with post data, passing in host group names in post data

3.4.1 Method: CLEAR without POST Data

DELETE /api/hostgroups/hostGroupName?clear=true

where hostName is a single host group name to be cleared

DELETE /api/hostgroups/hostGroupName1,hostGroupName2?clear=true

where hostGroupName1,hostGroupName2 is a comma-separated list of host group names to be cleared. Note that no-spaces are allowed in this HTTP path segment.

3.4.2 Method: CLEAR with POST Data

DELETE /api/hostgroups?clear=true

The post data should be formatted like a POST payload, but the only required field is the host Group Name (name). Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hostGroups>
  <hostGroup name="hostGroup-100” />
  <hostGroup name="hostGroup-101” />
</hostsGroups>

3.4.3 HTTP Status Codes

200 - Hosts were deleted successfully
500 - An internal server error occurred

3.4.4 Example Response

<results count='2' success='2' failure='0' entityType=’HostGroup’ operation=’Clear’>
  <result status='success' entity='hostGroup-100'
    location='http://localhost/monitor/api/hostgroups/hostGroup-100' />
  <result status='success' entity='hostGroup-101'
    location='http://localhost/monitor/api/hostgroups/hostGroup-101' />
</results>

4.0 Service APIs

(top)

4.1 Query Services

Retrieve services by query. There are two kinds of queries supported:

1. Retrieving a single service. Retrieves exactly one service object wrapped by an XML <service> element
2. Retrieving one or more services. Retrieves 1..n service objects wrapped by an XML <services> collection

4.1.1 Method: GET Services

GET /api/services?query=(query criteria see below)
GET /api/services?hostName

Method: GET a single service by name
GET /api/services/{serviceName}?hostName=(hostName)

4.1.2. HTTP Query and Path Parameters

Note: If neither a single serviceName path parameter or query query parameter is not provided, all hosts will be retrieved.

4.1.3 HTTP Headers

4.1.4 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

Non Queryable Fields

none

4.1.5 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all services
   GET /api/services
2. query for all services for the given host name
   GET /api/services?hostName=localhost
3. query for a single service named local_cpu_httpd under a hostName of localhost
   GET /api/services/local_cpu_httpd?hostName=localhost
4. query on a single property using LIKE operator
   GET /api/services?query=property.LastPluginOutput like ‘OK%’
5. query on a property using a range query, and monitor status field, order by a property
   GET /api/services?query=(property.ExecutionTime between 10 and 3500 and (monitorStatus <> 'UP')) order by property.ExecutionTime
6. query on service’s lastCheckTime using date functions
   GET /api/services?query=day(lastCheckTime) = 22 and month(lastCheckTime) = 5 and minute(lastCheckTime) > 43 order by lastCheckTime
7. query on joined attributes
   GET /api/services?query=stateType = 'HARD' and checkType = 'ACTIVE' and lastHardState = 'PENDING' and monitorStatus = 'OK'

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a serviceName(description) in the path parameter is always wrapped with a single <service> entity element. Properties are always wrapped in a <properties> collection element. All other fields are attributes.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<service id="1" appType="NAGIOS" description="local_cpu_httpd"
  monitorStatus="OK"
  lastStateChange="2013-05-22T09:44:46-07:00" hostName="localhost"
  stateType="HARD" checkType="ACTIVE" lastHardState="PENDING">
  <properties>
    <property name="LastPluginOutput"
      value="OK - total %CPU for process httpd : 0.0"/>
    <property name="ExecutionTime" value="187"/>
  </properties>
</service>

Result of queries are always wrapped in a <services> collection element, with one or more <service> subelements. Here is an XML example of the result of a query finding two services.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<services>
  <service id="1" appType="NAGIOS" description="local_cpu_httpd"
    monitorStatus="OK"
    lastStateChange="2013-05-22T09:44:46-07:00" hostName="localhost"
    stateType="HARD" checkType="ACTIVE" lastHardState="PENDING">
    <properties>
      <property name="LastPluginOutput"
        value="OK - total %CPU for process httpd : 0.0"/>
      <property name="ExecutionTime" value="187"/>
    </properties>
  </service>
  <service id="2" appType="NAGIOS" description="local_cpu_http"
         …
  </service>
</services>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Distinct Response Data - XML - JSON
  Query Response Data - XML - JSON

4.2 Create Services

Creates a batch (1..n) of new services in foundation database. Services will be created if they do not exist. If a service exists, it will be updated. Devices will also be created if they do not already exists.

If one or more service creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Service creation/update operation is returned back in the resultset described below with a status of success or failure.

4.2.1 Method: POST

POST /api/services

4.2.2 HTTP Headers

4.2.3 Request Parameters

4.2.4 Post Data Attributes

4.2.5 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<services>
  <service description="service-109"
    hostName="localhost" monitorServer="localhost"
    deviceIdentification="127.0.0.1"
    appType="NAGIOS"  monitorStatus="OK"
    lastStateChange="2013-05-22T09:36:47-07:00"
    stateType="HARD" checkType="ACTIVE" lastHardState="PENDING">
    <properties>
      <property name="Latency" value="950"/>
      <property name="ExecutionTime" value="7"/>
    </properties>
  </service>
</services>

More Post Data Examples: XML - JSON

4.2.6 HTTP Status Codes

200 - Zero or more services were created without any internal server errors
500 - An internal server error occurred

4.2.7 Example Response

In this example, 3 objects were attempted to be created. Only two succeeded, and one failed. The results collection also returns the location of the created or updated host which can be directly used by the GET operation.

<results count='3' success='2' failure='1' entityType=’Service’’ operation=’Update’>
  <result status='success' entity=’localhost:service-101’
    location='http://localhost/monitor/api/services/service-101?hostName=localhost' />
  <result status='success' entity='localhost:service-102'
    location='http://localhost/monitor/api/services/service-102?hostName=localhost’ />
  <result status='failure' message='Required field Application Type was not provided'
    entity='service-103' />
</results>

4.3 Delete Service

Deletes one or more services form Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more services on URL path
2. Delete with post data, passing in service names (descriptoins in post data
   Note that a hostName query parameter is always required for deletes.

4.3.1 Method: DELETE without POST Data

DELETE /api/services/service-101,service-102?hostName=localhost

4.3.2 Method: DELETE with POST Data

DELETE /api/services

The post data should be formatted like a POST payload, but the only required fields are the description and hostName. Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<services>
  <service description="service-100” hostName="localhost” />
  <service description="service-102” hostName=”localhost” />
</services>

4.3.3 HTTP Headers

4.3.4 HTTP Status Codes

200 - Services were deleted successfully
500 - An internal server error occurred

4.3.5 Example Response

<results count='2' success='2' failure='0' entityType=’Service’ operation=’Delete’>
  <result status='success' entity='localhost:service-101'
    message='Service Deleted />
  <result status='success' entity=’localhost:service-102'
    message=’Service Deleted’ />
</results>

5.0 Event APIs

(top)

5.1 Query Events

Retrieve events by query

5.1.1 Method: GET

GET /api/events?query=(query criteria see below)

5.1.2 Method: GET with event ids

GET /api/events/101,204,307

5.1.3 HTTP Query and Path Parameters

Note: **Query and eventIds are mutually exclusive. Both cannot be provided, but one or the other is required.

5.1.4 HTTP Headers

5.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

5.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query on two fields, and sort by report date
   GET /api/events?query=(appType='NAGIOS' and service=’http_alive’ and reportDate > '2013-06-01') order by reportDate
2. query on two attributes and order by none-queried field
   GET /api/events?query=device = '172.28.113.156' and severity = 'CRITICAL' order by operationStatus
3. Paging parameters first and count ...
   GET /api/events?query=service='http_alive'&first=20&count=10
4. query on all text messages starting with a prefix using LIKE operator
   GET /api/events?query=message like 'TCP OK%'
5. query on a property and field using LIKE operator
   GET /api/events?query=(property.SubComponent like 'localhost%' and property.ErrorType = 'SERVICE ALERT')
6. query on the messsage Count greater than 2 messages
   GET /api/events?query=count > 2
7. query on a not null field
   GET /api/events?query=appType is not null
8. Query using appType and last insert date between a date range
   GET /api/events?query=(appType='NAGIOS' and service='http_alive'
   and lastInsertDate between '2013-02-01' and '2013-04-01')
9. Query with a property greater than a threshold, and use a between range query on report date
   GET /api/events?query=(property.ExecutionTime > 800
   and (reportDate between '2013-02-01' and '2013-04-01'))
10. Query with a property greater than a threshold, and use a between range query on report date
    GET /api/events?query=(property.ExecutionTime > 800)
11. Range query using IN operator
    GET /api/events?query=host in ('qa-load-xp-1','qa-sles-11-64','do-win7-1')
12. Query on hostgroup using IN operator
    GET /api/events?query=hostgroup in ('IT','HG1')
13. Query by category
    GET /api/events?query=category = 'SG1'
14. Query on service group using IN operator
    GET /api/events?query=(serviceGroup in ('web-svr','SG1'))
15. Query on service group and host group using IN operator
    GET /api/events?query=(serviceGroup in ('web-svr','SG1') and hostgroup in ('IT','HG1'))
16. Retrieve a single event by event id
    GET /api/events?104
17. Retrieve a list of comma-separated events by id
    GET /api/events?104,207,306,494,507

Example Query Results in XML

Events are always wrapped in an <events> collection element. Here is an example of the result of a query finding two events. Properties are always wrapped in a <properties> collection element.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
  <event id="5" device="127.0.0.1" host="localhost" service="local_cpu_perl"
    operationStatus="ACCEPTED"
    monitorStatus="OK" severity="OK" applicationSeverity="OK"
    component="OK"
    priority="Lowest Priority in a scale from 1 -10" typeRule="UNDEFINED"
    textMessage="OK - total %CPU for process perl : 4.1"
    firstInsertDate="2013-05-17T07:46:12-07:00"
    lastInsertDate="2013-05-17T07:46:12-07:00"
    reportDate="2013-05-17T07:46:34.057-07:00"
    msgCount="1" appType="NAGIOS">
    <properties>
      <property name="ErrorType" value="SERVICE ALERT"/>
      <property name="SubComponent" value="localhost:local_cpu_perl"/>
    </properties>
  </event>
</events>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Distinct Response Data - XML - JSON

5.2 Create or Update Events

Creates a batch (1..n) of new events in foundation database. Events can be posted with or without a consolidation name. It is recommended to use consolidation names when events are often repeated for a device.

If one or more Event creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Event creation/update operation is returned back in the resultset described below with a status of success or failure.

5.2.1 Method: POST

POST /api/events

5.2.2 HTTP Headers

5.2.3 Required Post Data Attributes

5.2.4 Optional Post Data Attributes

5.2.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

5.2.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provideds' entity='234' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.2.7 Example Post Data

The post data should be formatted like in either XML or JSON:

{ "events": [
    {
        "host": "localhost",
        "monitorServer": "localhost",
        "service": "local_load",
        "appType": "NAGIOS",
        "textMessage": "This is a serious Nagios Message on Device 127.0.0.1",
        "monitorStatus": "UP",
        "severity": "SERIOUS",
        "consolidationName": "NAGIOSEVENT",
        "device": "127.0.0.1",
        "reportDate": "2013-06-02T10:55:32.943",
        "properties": {
            "Comments": "Additional comments",
            "Latency": "125.0"
        }
    }
]
}

More Post Data Examples: XML - JSON

5.3 Acknowledging Events

Acknowledge an event or set of events for either a given host, or for a host and service combination. Optionally, the ackowedgedBy and acknowledgeComment can be set on all events matching the host or host + service criteria. Additionally, the operationStatus for the updated events will be set to ACKNOWLEDGED. This API receives its post data in batch (always 1..n objects).

5.3.1 Method: POST

POST /api/events/ack

5.3.2 HTTP Headers

5.3.3 Required Post Data Attributes

5.3.4 HTTP Status Codes

200 - Events were acknowledged successfully
500 - An internal server error occurred

5.3.5 Example Post Data

The post data should be formatted in XML or JSON:

<acks>
  <ack
       appType="VEMA"
       hostName="STOR-datastore1"
       serviceDescription="summary.freeSpace"
       acknowledgedBy="cloudHub"
       acknowledgeComment="acknowledged ok service by cloudhub"
     />
/acks>

{ "acks" : [
       {
	"appType": "VEMA",
	"hostName": "STOR-datastore1",
	"serviceDescription": "summary.freeSpace",
	"acknowledgedBy": "cloudHub",
	"acknowledgeComment" : "acknowledged ok service by cloudhub"
       }
   ]
}

5.3.6 Example Response

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "Ack",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "STOR-datastore1 - summary.freeSpace",
    "status" : "success",
    "message" : "ack ' STOR-datastore1 - summary.freeSpace"
  } ],
  "count" : 1
}

5.4 UnAcknowledging Events

UnAcknowledge an event or set of events for either a given host, or for a host and service combination. Additionally, the operationStatus for the updated events will be reset to OPEN. This API receives its post data in batch (always 1..n objects).

5.4.1 Method: POST

POST /api/events/unack

5.4.2 HTTP Headers

5.4.3 Required Post Data Attributes

5.4.4 HTTP Status Codes

200 - Events were unacknowledged successfully
500 - An internal server error occurred

5.4.5 Example Post Data

The post data should be formatted in XML or JSON:

<unacks>
  <unack
       appType="VEMA"
       hostName="STOR-datastore1"
       serviceDescription="summary.freeSpace"
   />
</unacks>

{ "unacks" : [
     {
	"appType": "VEMA",
	"hostName": "STOR-datastore1",
	"serviceDescription": "summary.freeSpace"
     }
   ]
}

5.4.6 Example Response

{
  "successful" : 1,
  "failed" : 0,
  "entityType" : "UnAck",
  "operation" : "Update",
  "warning" : 0,
  "results" : [ {
    "entity" : "STOR-datastore1 - summary.freeSpace",
    "status" : "success",
    "message" : "unack ' STOR-datastore1 - summary.freeSpace"
  } ],
  "count" : 1
}

5.5 Update Event Property

Updates a batch (1..n) of existing events by primary key (ID) in foundation database with dynamic properties. Note this API only supports updating dynamic properties, not first-class field attributes.

5.5.1 Method: PUT

PUT /api/events

5.5.2 HTTP Headers

See Appendix A for examples of usage with Curl
   Post Data Example: XML - JSON

5.5.3 Required PUT Data

5.5.4 XML PUT Data Example

PUT /api/events/

5.5.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events>
  <event id="5">
    <properties>
      <property name="AcknowledgeComment" value="Received and acknowledged sir"></property>
      <property name="AcknowledgedBy" value="admin"></property>
    </properties>
  </event>
  <event id="6">
    <properties>
      <property name="AcknowledgeComment" value="Im good"></property>
      <property name="AcknowledgedBy" value="cloudhub"></property>
    </properties>
  </event>
</events>

{ "events":
 [
    {
      "id": "5",
      "properties":
        {
      	  "AcknowledgeComment": "Received and acknowledged sir",
      	  "LastPluginOutput": "output and more output"
        }
    },
    {
      "id": "6",
      "properties":
        {
      	  "AcknowledgeComment": "Im good",
      	  "LastPluginOutput": "output more output agaIN"
        }
    }
 ]
}

5.5.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provided' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.6 Delete Event

Deletes an event or events from foundation. This method does not take post parameters. It works solely off of the URL path.

5.6.1 Method: DELETE

DELETE /api/events/1,2,3

where 1,2,3 is a list of event ids to be deleted

5.6.2 HTTP Headers

5.6.3 XML DELETE Data Example

1. Delete 3 events
   DELETE /api/events/50,51,52

5.6.4 HTTP Status Codes

200 - Events were deleted successfully
500 - An internal server error occurred

5.6.5 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Event not found: 37’/>
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

5.6 Update Events (deprecated)

Updates a batch (1..n) of existing events in foundation database with a new operation status and optional parameters. This method does not take post parameters. It works solely off of the URL path and request parameters.

5.6.1 Method: PUT

PUT /api/events/1,2,3?opStatus=NOTIFIED

where 1,2,3 is a list of event ids to be updated and opStatus is a valid operationStatus

5.6.2 HTTP Headers

5.6.3 Query Parameters on PUT

5.7.4 XML PUT Data Example

1. PUT a new operation status for three events
   PUT /api/events/50,51,52?opStatus=NOTIFIED&updatedBy=admin&comments=testing+123

5.7.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred

5.7.6 Example Response

<results count='3' success='2' failure='1'>
  <result status='failure' message='Bad consolidation name provided' />
  <result status='success' entity='939'
    location='http://localhost/monitor/api/events/939' />
  <result status='success' entity='1024'
    location='http://localhost/monitor/api/hosts/1024' />
</results>

More Post Data Examples: XML - JSON

6.0 Devices APIs

(top)

6.1 Query Devices

Retrieve devices by query. There are two kinds of queries supported:

1. Retrieving a single device. Retrieves exactly one device wrapped by an XML <device> element
2. Retrieving one or more devices . Retrieves 1..n device objects wrapped by an XML <devices> collection

6.1.1 Method: GET Device

GET /api/devices?query=(query criteria see below)

6.1.2 Method: GET a single device by identification

GET /api/devices/{deviceIdentification}

6.1.3 HTTP Query and Path Parameters

Note: **If neither a deviceIdentification path parameter or query query parameter is not provided, all devices will be retrieved.

6.1.4 HTTP Headers

6.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

6.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all devices, with shallow depth
   GET /api/devices
2. query for all devices, with deep depth
   GET /api/devices?depth=deep
3. query for a single device identified by 127.0.0.1, with depth of shallow
   GET /api/devices/127.0.0.1
4. query for a single device identified by 127.0.0.1, with depth of deep
   GET /api/devices/127.0.0.1?depth=deep
5. a like query to find all devices starting with identification of 172.28.113.* and filter by host name
   GET /api/devices?query=identification like '172.28.113%' and d.hosts.hostName = 'qa-sles-11-64-2'
6. a simple or query on the display names ordered by name (displayName)
   GET /api/devices?query=displayName = 'demo' or displayName = 'malbec' order by name
7. query for one or more display Names using in query syntax
   GET /api/devices?query=name in ('demo','malbec','sql-2008','127.0.0.1'')

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a device identifier in the path parameter is always wrapped with a single <device> entity element. Here is an XML example of the result of a query finding one device. All fields are displayed as attributes.

<device id="1"
  identification="127.0.0.1"
  displayName="127.0.0.1"
  description="Device localhost"/>

Result of queries are always wrapped in a <devices> collection element, with one or more <device> subelements.

<devices>
  <device id="1” identification="127.0.0.1"
    displayName="127.0.0.1"
    description="Device localhost"/>
  <device id="2” identification="172.28.113.166"
    displayName="QA server"
    description="Device for QA Testing"/>
</devices>

Host and Monitor Server collections are only displayed when depth = deep. These collections are represented as elements.

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Response Data - XML - JSON
  Deep Response Data - XML - JSON

6.2 Create Devices

Creates a batch (1..n) of new devices in foundation database. Devices will be created if they do not exist. If a device exists, it will be updated. You can also specify one or more hosts to be created or associated with the device. Note these hosts will be created if they do not already exist in the system.

If one or more device creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Device creation/update operation is returned back in the resultset described below with a status of success or failure.

6.2.1 Method: POST

POST /api/devices

6.2.2 HTTP Headers

6.2.3 Post Data Attributes and Elements

6.2.4 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<devices>
  <device displayName="device-900" identification="172.28.128.100">
    <hosts>
      <host hostName='abc.com' description='Host ABC'/>
      <host hostName='def.com' description='Host DEF'/>
    </hosts>
  </device>
</devices>

More Post Data Examples: XML - JSON

6.2.5 HTTP Status Codes

200 - Zero or more devices were created without any internal server errors
500 - An internal server error occurred

6.2.6 Example Response

In this example, we use the POST data above. One device was attempted to be created. Additionally, we tried to add two hosts to the device.
Note that the results collection also returns the location of the created or updated device which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="1" failed="0" entityType="Device"
       operation="Update" warning="0" count="1">
  <result>
    <entity>172.28.128.100</entity>
    <location>
    http://localhost/api/devices/172.28.128.100</location>
    <status>success</status>
  </result>
</results>

6.3 Delete Devices

Deletes one or more devices from the Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more devices names on URL path
2. Delete with post data, passing in device identifications in post data

6.3.1 Method: DELETE without POST Data

DELETE /api/devices/127.0.0.1

where 127.0.0.1 is a single device identification to be deleted

DELETE /api/devices/127.0.0.1,172.28.113.166
where the comma-separated list of two device identifiers. Note that no-spaces are allowed in this HTTP path segment.

6.3.2 Method: DELETE with POST Data

DELETE /api/devices

The post data should be formatted like a POST payload, but the only required field is the device Identification. Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<devices>
  <device identification="172.28.113.166” />
  <device identification="172.28.113.168” />
</devics>

6.3.3 HTTP Headers

6.3.4 HTTP Status Codes

200 - Hosts were deleted successfully
500 - An internal server error occurred

6.3.5 Example Response

<results count='2' success='2' failure='0' entityType=Device operation=’Delete’>
  <result status='success' entity='172.28.113.166’
       location='http://localhost/monitor/api/devices/172.28.113.166’' />
  <result status='success' entity='172.28.113.168’
       location='http://localhost/monitor/api/devices/172.28.113.168’ />
</results>

7.0 Statistics APIs

(top)

The Statistics APIs query real time monitor statistics. These APIs are read only. The Statistics APIs are categorized by Totals, Hosts, Host Groups, Services, and Availability.

All Statistics queries support both XML and JSON

7.1 HTTP Headers

7.2 Total Statistics

Retrieve statistics by totals, system wide. Total statistics target two kinds of statistical data:

1. Host Total Statistics
2. Service Total Statistics

Statistics totals are grouped by the status of the statistical data. Total counts are presented for the number of hosts in the system, number of services in the system, and then individual counts are displayed for each status (“DOWN”, “UP”, ….) either by service or by host counts.

7.2.1 Method: GET Total Statistics for Hosts

GET /api/statistics/totals/hosts

7.2.2 Method: GET Total Statistics for Services

GET /api/statistics/totals/services

7.2.3 Example Queries

1. query for total statistics by hosts
   GET /api/statistics/totals/hosts

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistic totalHosts="20"
          totalServices="131" name="_ALL_"
          availability="75.0">
     <properties>
       <property name="DOWN" count="0" />
       <property name="UNREACHABLE" count="0" />
       <property name="PENDING" count="0" />
       <property name="UP" count="15" />
       <property name="SCHEDULED DOWN" count="0" />
       <property name="UNSCHEDULED DOWN" count="5" />
     </properties>
   </statistic>

2. query for total statistics by services
   GET /api/statistics/totals/services

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistic totalHosts="20"
          totalServices="131" name="{color}{color:#4a86e8}{_}ALL{_}{color}{color:#4a86e8}"{color}
          availability="0.0">
     <properties>
       <property name="CRITICAL" count="0" />
       <property name="WARNING" count="2" />
       <property name="UNKNOWN" count="0" />
       <property name="OK" count="114" />
       <property name="PENDING" count="0" />
       <property name="SCHEDULED CRITICAL" count="0" />
       <property name="UNSCHEDULED CRITICAL" count="15" />
     </properties>
   </statistic>

7.3 Host Statistics

Retrieve statistics by hosts.

Hosts statistics accumulates statistical data for hosts. Counts are filtered by the list of hosts in the request. Individual counts are displayed for each status (e.g. "DOWN", "UP").

7.3.1 Method: GET Statistics by Host for Specified Hosts

GET /api/statistics/hosts/{one or more comma separated host names}

7.3.2 Example Queries

1. query for statistics for the five given host names
   GET /api/statistics/hosts/localhost,172.28.113.151,demo,malbec,qa-load-xp-1

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistic totalHosts="5" totalServices="0"
          name="'localhost','172.28.113.151','demo','malbec','qa-load-xp-1'"
          availability="0.0">
     <properties>
       <property name="DOWN" count="0" />
       <property name="UNREACHABLE" count="0" />
       <property name="PENDING" count="0" />
       <property name="UP" count="5" />
       <property name="SCHEDULED DOWN" count="0" />
       <property name="UNSCHEDULED DOWN" count="0" />
     </properties>
   </statistic>

7.4 Host Group Statistics

Retrieve statistics by host groups.

Hosts Group statistics accumulates statistical data for host groups. Counts are filtered by the list of hosts in the request. Individual counts are displayed for each status (e.g. "DOWN", "UP").

Host Group statistics differ from Host statistics in that there is are statistics elements for each host group in the system

7.4.1 Method: GET Statistics for all host groups

GET /api/statistics/hostgroups

7.4.2 Method: GET Statistics for a list of host groups

GET /api/statistics/hostgroups/{one or more comma-separated host group names}

7.4.3 Example Queries

1. query statistics for all host groups
   GET /api/statistics/hostsgroups

   <statistics>
     <statistic totalHosts="2" totalServices="23" name="IT"
     availability="100.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="2" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="0" />
       </properties>
     </statistic>
     <statistic totalHosts="1" totalServices="4" name="HG1"
     availability="100.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="1" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="0" />
       </properties>
     </statistic>
     <statistic totalHosts="5" totalServices="75" name="Engineering"
     availability="60.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="3" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="2" />
       </properties>
     </statistic>
     <statistic totalHosts="10" totalServices="55"
     name="Linux Servers" availability="100.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="10" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="0" />
       </properties>
     </statistic>
   </statistics>

2. query statistics for one or more host groups comma separated
   GET /api/statistics/hostsgroups/Linux+Servers,Engineering

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="10" totalServices="55"
     name="Linux Servers" availability="100.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="10" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="0" />
       </properties>
     </statistic>
     <statistic totalHosts="5" totalServices="75" name="Engineering"
     availability="60.0">
       <properties>
         <property name="DOWN" count="0" />
         <property name="UNREACHABLE" count="0" />
         <property name="PENDING" count="0" />
         <property name="UP" count="3" />
         <property name="SCHEDULED DOWN" count="0" />
         <property name="UNSCHEDULED DOWN" count="2" />
       </properties>
     </statistic>
   </statistics>

7.5 Service Statistics

Retrieve statistics by services.

Service statistics accumulates statistical data for for service counts grouped by service status. Individual counts are displayed for each status (e.g. "DOWN", "UP"). Service statistics supports filtering by:

1. a list of all Host Groups (no filtering)
2. filter by a list of Hosts
3. filter by a list of Host Groups
4. filter by a list of Service Groups

7.5.1 Method: GET All Service Statistics Grouped by Host Groups

GET /api/statistics/services

7.5.2 Method: GET Service Statistics Filtered by Hosts

GET /api/statistics/services/hosts/{comma separated list of host names}

7.5.3 Method: GET Service Statistics Filtered by Host Groups

GET /api/statistics/services/hostgroups/{comma separated list of host group names}

7.5.4 Method: GET Service Statistics Filtered by Service Groups

GET /api/statistics/services/servicegroups/{comma separated list of services group names}

7.5.5 Method: GET All Service Statistics Grouped by Service Groups

GET /api/statistics/services/servicegroups

7.5.6 Example GET All Service Statistics Grouped by Host Group

1. query all service statistics grouped by all host groups
   GET /api/statistics/services

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="2" totalServices="23" name="IT"
     availability="86.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="20" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="3" />
       </properties>
     </statistic>
     <statistic totalHosts="1" totalServices="4" name="HG1"
     availability="50.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="2" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="2" />
       </properties>
     </statistic>
     <statistic totalHosts="5" totalServices="75" name="Engineering"
     availability="88.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="2" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="66" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="7" />
       </properties>
     </statistic>
     <statistic totalHosts="10" totalServices="55"
     name="Linux Servers" availability="94.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="52" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="3" />
       </properties>
     </statistic>
     <statistic totalHosts="4" totalServices="12" name="Support"
     availability="75.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="9" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="3" />
       </properties>
     </statistic>
     <statistic totalHosts="5" totalServices="13" name="Eng-QA"
     availability="92.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="12" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="1" />
       </properties>
     </statistic>
     <statistic totalHosts="4" totalServices="9" name="Eng-test"
     availability="66.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="6" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="3" />
       </properties>
     </statistic>
   </statistics>

7.5.7 Example GET Service Statistics Filtered by Hosts

1. query service statistics grouped by hosts for two hosts
   GET /api/statistics/services/hosts/localhost,support-xp-1

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="1" totalServices="21" name="localhost"
     availability="0.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="19" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="2" />
       </properties>
     </statistic>
     <statistic totalHosts="1" totalServices="1" name="support-xp-1"
     availability="0.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="0" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="1" />
       </properties>
     </statistic>
   </statistics>

7.5.8 Example GET Service Statistics Filtered by Host Groups

1. query service statistics grouped by host groups for two host groups
   GET /api/statistics/services/hostgroups/Engineering,Linux+Servers

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="5" totalServices="75" name="Engineering"
     availability="88.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="2" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="66" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="7" />
       </properties>
     </statistic>
     <statistic totalHosts="10" totalServices="55"
     name="Linux Servers" availability="94.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="52" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="3" />
       </properties>
     </statistic>
   </statistics>

7.5.9 Example GET Service Statistics Filtered by Service Groups

1. query service statistics grouped by service groups for one service group
   GET /api/statistics/services/servicegroups/SG1

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="0" totalServices="2" name="SG1"
     availability="100.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="2" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="0" />
       </properties>
     </statistic>
   </statistics>

7.5.10 Example GET All Service Statistics Grouped by Service Groups

1. query all service statistics grouped by all host groups
   GET /api/statistics/services/servicegroups

   <?xml version="1.0" encoding="utf-8" standalone="yes"?>
   <statistics>
     <statistic totalHosts="0" totalServices="8" name="web-svr"
          availability="75.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="6" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="2" />
       </properties>
     </statistic>
     <statistic totalHosts="0" totalServices="2" name="SG1"
          availability="100.0">
       <properties>
         <property name="CRITICAL" count="0" />
         <property name="WARNING" count="0" />
         <property name="UNKNOWN" count="0" />
         <property name="OK" count="2" />
         <property name="PENDING" count="0" />
         <property name="SCHEDULED CRITICAL" count="0" />
         <property name="UNSCHEDULED CRITICAL" count="0" />
       </properties>
     </statistic>
   </statistics>

7.6 Availability Statistics

Retrieves availability percentage statistics for services and hosts.

Availability statistics return a percentage of availability (the server is up and running) of all services or hosts for a given criteria.

Types of Availability Queries

1. Host Availability by Host Group Name
2. Service Availability by Host Group Name
3. Service Availability by Service Group Name

7.6.1 Method: GET Host Availability by Host Group Name

GET /api/statistics/availability/hosts?hostGroup={hostGroupName}

7.6.2 Method: GET Service Availability by Host Group Name

GET /api/statistics/availability/services?hostGroup={hostGroupName}

7.6.3 Method: GET Service Availability by Service Group Name

GET /api/statistics/availability/services?serviceGroup={serviceGroupName}

7.6.4 Example GET Host Availability by Host Group Name

GET /api/statistics/availability/hosts?hostGroup=Engineering

?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="100.0" queryBy="hosts"
       queryParam="hostGroup" queryValue="HG1" />

7.6.5 Example GET Service Availability by Host Group Name

GET /api/statistics/availability/services?hostGroup=Linux+Servers

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="50.0" queryBy="services"
       queryParam="hostGroup" queryValue="HG1" />

7.6.6 Example GET Service Availability by Service Group Name

GET /api/statistics/availability/services?serviceGroup=SG1

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="100.0" queryBy="services"
       queryParam="serviceGroup" queryValue="SG1" />

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON

8.0 Category APIs

(top)

8.1 Query Categories

Retrieve categories by query. There are two kinds of queries supported:

1. Retrieving a single category. Retrieves exactly one category wrapped by an XML <category> element
2. Retrieving one or more categories . Retrieves 1..n category objects wrapped by an XML <categories> collection

8.1.1 Method: GET Category

GET /api/categories?query=(query criteria see below)

8.1.2 Method: GET a single category by unique category name

GET /api/categories/{categoryName}

8.1.3 HTTP Query and Path Parameters

*Note: **If neither a categoryName path parameter or query query parameter is not provided, all categories will be retrieved._

8.1.4 HTTP Headers

8.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

8.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all categories, with shallow depth
   GET /api/categories
2. query for all categories, with deep depth, order by name descending
   GET /api/categories?depth=deep&query=order by name desc
3. query for a single category named ‘HeavyLoad’ with depth of shallow
   GET /api/categories/HeavyLoad
4. query for a single category named ‘TopPriority’ with depth of deep
   GET /api/categories/TopPriority?depth=deep
5. a like query to find all categories starting with ‘SERVICE’_
   GET /api/categories?query=name like 'SERVICE_%'
6. query for all categories of type ‘SERVICE_GROUP’ ordered by name
   GET /api/categories?query=entityType.name = 'SERVICE_GROUP' order by name
7. query for one or more category names using IN query syntax
   GET /api/categories?query=name in (‘americas’,’east-region’,’west-region’’)
8. query for one or more category names by object id of child collection of Category Entities
   GET /api/categories?query=c.categoryEntities.objectID = 22

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a category name in the path parameter is always wrapped with a single <category> entity element. Here is an XML example of the result of a query finding one category. All fields are displayed as attributes.

<category id="2" name="SG1" description="Service Group 1"
       entityTypeName="SERVICE_GROUP" />

Result of queries are always wrapped in a <categories> collection element, with one or more <category> subelements.

<categories>
  <category id="2" name="SG1" description='Service Group 1'
    entityTypeName="SERVICE_GROUP" />
  <category id="1" name="North" description='North Region servers'
    entityTypeName="SERVICE_GROUP" />
</categories>

The full entity type will be displayed when depth = deep. Also, category entities are displayed.

<category id="2" name="SG1" entityTypeName="SERVICE_GROUP">
  <entityType id="23" name="SERVICE_GROUP"
    description="com.groundwork.collage.model.impl.ServiceGroup"
    isLogicalEntity="true" applicationTypeSupported="false" />
    <entities>
      <entity id="10" objectID="3" entityTypeId="2" />
      <entity id="9" objectID="44" entityTypeId="2" />
    </entities>
</category>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Shallow Response Data - XML - JSON
  Deep Response Data - XML - JSON

8.2 Create or Update Categories

Persist a batch (1..n) of categories in foundation database. Categories will be created if they do not exist. If a category exists, it will be updated. You can also specify one or more category entities to be created or associated with the category. Category entities will be created if they do not already exist in the system.

If one or more category creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Category creation/update operation is returned back in the resultset described below with a status of success or failure.

8.2.1 Method: POST

POST /api/categories

8.2.2 HTTP Headers

8.2.3 Post Data Attributes and Elements

8.2.4 CategoryEntity Attributes and Elements

8.2.5 XML POST Data Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<categories>
  <category name="west-region" description='servers in the west region'
    entityTypeName='SERVICE_GROUP'/>
  <category name="east-region" description='servers in the east region'
     entityTypeName='SERVICE_GROUP'/>
</categories>

More Post Data Examples: XML - JSON

8.2.6 HTTP Status Codes

200 - Zero or more categories were created without any internal server errors
500 - An internal server error occurred

8.2.7 Example Response

In this example, we use the POST data above. Two categories were successfully created.

Note that the results collection also returns the location of the created or updated category which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Category"
       operation="Update" warning="0" count="2">
  <result>
    <entity>west-region</entity>
    <location>http://localhost/api/categories/west-region</location>
    <status>success</status>
  </result>
  <result>
    <entity>east-region</entity>
    <location>http://localhost/api/categories/east-region</location>
    <status>success</status>
  </result>
</results>

8.3 Delete Categories

Deletes one or more categories from the Collage database. There are two methods of deletion:

1. Delete without post data, passing in one or more category names on URL path
2. Delete with post data, passing in category names via post data

8.3.1 Method: DELETE without POST Data

DELETE /api/categories/west-region

where west-region is the name of the category to delete

DELETE /api/categories/west-region,east-region
A comma-separated list of two category names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.

8.3.2 Method: DELETE with POST Data

DELETE /api/categories

The post data should be formatted like a POST payload, but the only required field is the category name.

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<categories>
  <category name="west-region"/>
  <category name="east-region"/>
</categories>

8.3.3 HTTP Headers

8.3.4 HTTP Status Codes

200 - Categories were deleted successfully
500 - An internal server error occurred

8.3.5 Example Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Category"
       operation="Delete" warning="0" count="2">
  <result>
    <entity>west-region</entity>
    <location>http://localhost/api/categories/west-region</location>
    <status>success</status>
  </result>
  <result>
    <entity>east-region</entity>
    <location>http://localhost/api/categories/east-region</location>
    <status>success</status>
  </result>
</results>

9.0 Graph APIs

(top)

The Graph API generates real-time RRD graphs based on a set of input parameters. Depending on the provided query parameters, one or more graphs may be created. Graphs are created per host and optionally per service. The hostName parameter is required. If the service parameter is not provided, graphs will be generated for each service type for the given host. If the application type is not provided, defaults to NAGIOS. Start and end date are represented in seconds since start of the epoch. Both start and end dates are optional. If end date is not provided, the end date defaults to now. If start date is not provided, the start date defaults to 24 hours ago.

All Graph requests support both XML and JSON

9.1 HTTP Headers

9.2 Query Fields

9.3 Method: GET Graphs

GET /api/graphs

9.4 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all services for the host named “localhost”
   GET /api/graphs?hostName=localhost
2. query for all services for the host named localhost and service named “http_alive”
   GET /api/graphs?hostName=localhost&serviceName=http_alive
3. query for all services for the host named “localhost”, start date = August 1, 2013
   GET /api/graphs?hostName=localhost&startDate=61333484400000
4. query all services host named “localhost”, start date = August 1, 2013, graph width 600 pixels
   GET /api/graphs?hostName=localhost&startDate=61333484400000&graphWidth=600

The results are returned in either JSON or XML, with a collection of graph elements, each containing a label attribute and base64 encoded representation of the image (graph).

9.5 Example Results

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<graphs>
  <graph label="local_process_gw_listener: Process Count">
    <graph>...(base64 encoding)...</graph>
  </graph>
  <graph label="local_mem_nagios: Memory Utilization">
    <graph>...(base64 encoding)...</graph>
  </graph>
  <graph label="local_load: Load Averages">
    <graph>...(base64 encoding)...</graph>
  </graph>
</graphs>

10.0 Metadata APIs

(top)

10.1 Query Metadata

Retrieve metadata files describing the REST services and the schema of the objects passed in the services. Two resources are provided:

1. The Web Application Description Language (WADL) - WADL is a machine-readable XML description of HTTP-based web applications (typically REST web services). WADL models the resources provided by a service and the relationships between them. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser.[1]
2. The XML Schema (XSD) - XSD is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntactical constraints imposed by XML.

The WADL file returns an XML document describing all services available in the Foundation REST services. The XSD file returns the schema definitions for all data transfer objects passed in the REST services.

10.1.1 Method: GET WADL Metadata

GET /api/meta/wadl

10.1.2 Method: GET XSD Schema Metadata

GET /api/meta/xsd

11.0 Property Type APIs

(top)

11.1 Query Property Types

Retrieve property types by query. There are two kinds of queries supported:

1. Retrieving a single property type. Retrieves exactly one property type wrapped by an XML <propertyType
   > element
2. Retrieving one or more property types . Retrieves 1..n property type objects wrapped by an XML <propertyTypes> collection

11.1.1 Method: GET Property Types

GET /api/propertytypes?query=(query criteria see below)

11.1.2 Method: GET a single property type by unique property type name

GET /api/propertytypes/{propertyTypeName}

11.1.3 HTTP Query and Path Parameters

Note: **If neither a propertyTypeName path parameter or query query parameter is not provided, all propertyTypes will be retrieved.

11.1.4 HTTP Headers

11.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

The dataType field cannot be directly queried. It is calculated field, and must be queried with special syntax:

11.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all property types
   GET /api/propertytypes
2. query for all property types, order by name descending
   GET /api/propertytypes?query=order by name desc
3. query for a single propertyType named ‘ExecutionTime’
   GET /api/propertytypes/ExcecutionTime
4. a like query to find all property types starting with ‘RRD’
   GET /api/propertytypes?query=name like 'RRD%'
5. query for all property types of type INTEGER ordered by name
   GET /api/propertytypes?query=isInteger = true order by name
6. query for all property types of type BOOLEAN
   GET /api/propertytypes?query=isBoolean = true
7. query for one or more proper names using IN query syntax
   GET /api/propertytypes?query=name in (‘ExecutionTime’,’DeactivationTime’,’RRDCommand’’)

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a property type name in the path parameter is always wrapped with a single <propertyType> entity element. Here is an XML example of the result of a query finding one property type. All fields are displayed as attributes.

<propertyType id="39" name="AcknowledgedBy" description="(none)"  dataType="STRING />

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more <propertyType> subelements.

<propertyTypes>
  <propertyType id="39" name="AcknowledgedBy" description="(none)"  dataType="STRING” />
  <propertyType id="29" name="ExecutionTime" description="(none)"  dataType="DOUBLE” />
</propertyTypes>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Response Data - XML - JSON

11.2 Create or Update Property Types

Persist a batch (1..n) of property types in foundation database. Property types will be created if they do not exist. If a property type exists, it will be updated.

If one or more property type creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Property Type creation/update operation is returned back in the resultset described below with a status of success or failure.

11.2.1 Method: POST

POST /api/propertytypes

11.2.2 HTTP Headers

11.2.3 Post Data Attributes and Elements

11.2.4 XML POST Data Example

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<propertyTypes>
  <propertyType name="unusedCPU" description="Measures unused CPU usage" dataType="DOUBLE" />
  <propertyType name="virtualName" description="Name of virtual app" dataType="STRING" />
</propertyTypes>

More Post Data Examples: XML - JSON

11.2.5 HTTP Status Codes

200 - Zero or more property types were created without any internal server errors
500 - An internal server error occurred

11.2.6 Example Response

In this example, we use the POST data above. Two property types were successfully created.

Note that the results collection also returns the location of the created or updated property type which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="PropertyType"
       operation="Update" warning="0" count="2">
  <result>
    <entity>unusedCPU</entity>
    <location>http://localhost/api/propertytypes/unusedCPU</location>
    <status>success</status>
  </result>
  <result>
    <entity>virtualName</entity>
    <location>http://localhost/api/propertytypes/virtualName</location>
    <status>success</status>
  </result>
</results>

11.3 Delete Property Types

Deletes one or more property types from the Collage database.

11.3.1 Method: DELETE

DELETE /api/propertytypes/name1

where name1 is the name of the property type to delete

DELETE /api/propertytypes/name1,name2 ...
A comma-separated list of two property names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.

11.3.2 HTTP Headers

11.3.3 HTTP Status Codes

200 - Property types were deleted successfully
500 - An internal server error occurred

11.3.4 Example Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="PropertyType"
       operation="Delete" warning="0" count="2">
  <result>
    <entity>name1</entity>
    <message>Property type deleted</message>
    <status>success</status>
  </result>
  <result>
    <entity>name2</entity>
    <message>Property type deleted</message>
    <status>success</status>
  </result>
</results>

12.0 Application Type APIs

(top)

12.1 Query Application Types

Retrieve application types by query. There are two kinds of queries supported:

1. Retrieve a single applicationType. Retrieves exactly one applicationType wrapped XML <applicationType> element
2. Retrieve one or more application types . Retrieves 1..n application type objects wrapped by an XML <applicationTypes> collection

12.1.1 Method: GET Application Types

GET /api/applicationtypes?query=(query criteria see below)

12.1.2 Method: GET a single Application Type by unique application type name

GET /api/applicationtypes/{applicationTypeName}

12.1.3 HTTP Query and Path Parameters

Note: **If neither a applicationTypeName path parameter or query query parameter is not provided, all applicationTypes will be retrieved.

12.1.4 HTTP Headers

12.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.

12.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all application types
   GET /api/applicationtypes
2. query for all application types, order by name descending
   GET /api/applicationtypes?query=order by name desc
3. query for a single applicationType named ‘NAGIOS’
   GET /api/applicationtypes/NAGIOS
4. a like query to find all application types in list
   GET /api/applicationtypes?query=name in ('SYSTEM','SNMPTRAP','SYSLOG')

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a application type name in the path parameter is always wrapped with a single <applicationType> entity element. Here is an XML example of the result of a query finding one application type. All fields are displayed as attributes.

Note that Application Types return a number of fields that are calculated and thus it is not possible to query them:

1. entityProperties
2. entityTypes
3. any capitalized property

   <applicationType id="200" name="VEMA"
          description="Virtual Environment Monitor Agent"
          stateTransitionCriteria="Device;Host;ServiceDescription">
     <properties>
            ....
     </properties>
     <entityProperties>
         ...
     </entityProperties>
     <entityTypes>
        ...
     </entityTypes>
   </applicationType>

   Result of queries are always wrapped in a <applicationTypes> collection element, with one or more <applicationType> subelements.

   <applicationTypes
     <applicationType id="107" name="SYSLOG"
          description="SYSLOG Application"
          stateTransitionCriteria="Device">
     ...
     </applicationType>
     <applicationType id="200" name="VEMA"
          description="Virtual Environment Monitor Agent"
          stateTransitionCriteria="Device;Host;ServiceDescription">
   </applicationTypes>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Response Data - XML - JSON

12.2 Create or Update Application Types

Persist a batch (1..n) of application types in foundation database. Application types will be created if they do not exist. If a application type exists, it will be updated.

If one or more application type creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Application Type creation/update operation is returned back in the resultset described below with a status of success or failure.

Posts allow for associating entity properties with an application type to define the valid EntityType/PropertyType values for this ApplicationType.

<entityProperty>
  <entityType>HOST_STATUS</entityType>
  <propertyType>isAcknowledged</propertyType>
  <sortOrder>52</sortOrder>
</entityProperty>

12.2.1 Method: POST

POST /api/applicationtypes

12.2.2 HTTP Headers

12.2.3 Post Data Attributes and Elements

12.2.4 XML POST Data Example

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<applicationTypes>
  <applicationType name="DAVE" description="Virtual Environment Monitor Agent"
       stateTransitionCriteria="Device;Host;ServiceDescription">
  <entityProperties>
    <entityProperty>
      <entityType>HOST_STATUS</entityType>
      <propertyType>isAcknowledged</propertyType>
      <sortOrder>52</sortOrder>
    </entityProperty>
    <entityProperty>
      <entityType>HOST_STATUS</entityType>
      <propertyType>LastPluginOutput</propertyType>
      <sortOrder>53</sortOrder>
    </entityProperty>
    <entityProperty>
      <entityType>SERVICE_STATUS</entityType>
      <propertyType>LastPluginOutput</propertyType>
      <sortOrder>54</sortOrder>
    </entityProperty>
    <entityProperty>
      <entityType>SERVICE_STATUS</entityType>
      <propertyType>PerformanceData</propertyType>
      <sortOrder>55</sortOrder>
    </entityProperty>
  </entityProperties>
  </applicationType>
</applicationTypes>

More Post Data Examples: XML - JSON

12.2.5 HTTP Status Codes

200 - Zero or more application types were created without any internal server errors
500 - An internal server error occurred

12.2.6 Example Response

In this example, we use the POST data above. Two application types were successfully created.

Note that the results collection also returns the location of the created or updated application type which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="ApplicationType"
       operation="Update" warning="0" count="2">
  <result>
    <entity>NEWAPP</entity>
    <location>http://localhost/api/applicationtypes/NEWAPP</location>
    <status>success</status>
  </result>
  <result>
    <entity>NEWAPP2</entity>
    <location>http://localhost/api/applicationtypes/NEWAPP2</location>
    <status>success</status>
  </result>
</results>

12.3 Delete Application Types

Deletes one or more application types from the Collage database.

12.3.1 Method: DELETE

DELETE /api/applicationtypes/name1

where name1 is the name of the application type to delete

DELETE /api/applicationtypes/name1,name2 ...
A comma-separated list of two application names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.

12.3.2 HTTP Headers

12.3.3 HTTP Status Codes

200 - Application types were deleted successfully
500 - An internal server error occurred

12.3.4 Example Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="ApplicationType"
       operation="Delete" warning="0" count="2">
  <result>
    <entity>name1</entity>
    <message>Application type deleted</message>
    <status>success</status>
  </result>
  <result>
    <entity>name2</entity>
    <message>Application type deleted</message>
    <status>success</status>
  </result>
</results>

13.0 Entity Type APIs

(top)

13.1 Query Entity Types

Retrieve entity types by query. There are two kinds of queries supported:

1. Retrieve a single entityType. Retrieves exactly one entityType wrapped XML <entityType> element
2. Retrieve one or more entity types . Retrieves 1..n entity type objects wrapped by an XML <entityTypes> collection

13.2 Method: GET Entity Types

GET /api/entitytypes?query=(query criteria see below)

13.3 Method: GET a single Entity Type by unique entity type name

GET /api/entitytypes/{entityTypeName}

13.4 HTTP Query and Path Parameters

Note: **If neither a entityType path parameter or query query parameter is not provided, all entityTypes will be retrieved.

13.5 HTTP Headers

13.6 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.
***The fields entity

13.7 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all entity types
   GET /api/entitytypes
2. query for all entity types, order by name descending
   GET /api/entitytypes?query=order by name desc
3. query for a single entityType named ‘DEVICE’
   GET /api/entitytypes/DEVICE
4. a like query to find all entity types in list
   GET /api/entitytypes?query=name in (‘DEVICE','HOST,'CATEGORY)

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a entity type name in the path parameter is always wrapped with a single <entityType> element. Here is an XML example of the result of a query finding one entity type. All fields are displayed as attributes.

<entityType id="15" name="STATE_TYPE"
       description="com.groundwork.collage.model.impl.StateType"
       isLogicalEntity="false" applicationTypeSupported="false" />

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more <propertyType> subelements.

<entityTypes>
  <entityType id="7" name="APPLICATION_TYPE"
       description="com.groundwork.collage.model.impl.ApplicationType"
       isLogicalEntity="false" applicationTypeSupported="false" />
  <entityType id="8" name="CATEGORY"
       description="com.groundwork.collage.model.impl.Category"
       isLogicalEntity="false" applicationTypeSupported="false" />
  <entityType id="9" name="CHECK_TYPE"
       description="com.groundwork.collage.model.impl.CheckType"
       isLogicalEntity="false" applicationTypeSupported="false" />
  <entityType id="10" name="COMPONENT"
       description="com.groundwork.collage.model.impl.Component"
       isLogicalEntity="false" applicationTypeSupported="false" />
</entityTypes>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Response Data - XML - JSON

14.0 Consolidation APIs

(top)

14.1 Query Consolidations

Retrieve consolidations by query. There are two kinds of queries supported:

1. Retrieve a single consolidation. Retrieves exactly one consolidation wrapped XML <consolidation> element
2. Retrieve one or more consolidations . Retrieves 1..n consolidation objects wrapped by an XML <consolidations> collection

14.1.1 Method: GET Consolidations

GET /api/consolidations?query=(query criteria see below)

14.1.2 Method: GET a single Consolidation by unique consolidation name

GET /api/consolidations/{consolidationName}

14.1.3 HTTP Query and Path Parameters

Note: **If neither a consolidationName path parameter or query query parameter is not provided, all consolidations will be retrieved.

14.1.4 HTTP Headers

14.1.5 Query Fields

Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine.
***The fields entity

14.1.6 Example Queries

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. query for all consolidations
   GET /api/consolidations
2. query for all consolidations, order by name descending
   GET /api/consolidations?query=order by name desc
3. query for a single consolidation named 'SYSTEM'
   GET /api/consolidations/SYSTEM
4. a like query to find all consolidations in list
   GET /api/consolidations?query=like 'SY%'

Example Query Results in XML

The normal results of a query will result in either HTTP 200 OK status or a HTTP 404 NOT FOUND status.

Results of requesting a single entity with a consolidation name in the path parameter is always wrapped with a single <consolidation> entity element. Here is an XML example of the result of a query finding one consolidation. All fields are displayed as attributes.

<consolidation id="4" name="SYSLOG"
       criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent"/>

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more <propertyType> subelements.

<consolidations>
  <consolidation id="2" name="NAGIOSEVENT"
  criteria="Device;MonitorStatus;OperationStatus;SubComponent;ErrorType" />
  <consolidation id="3" name="SNMPTRAP" criteria="OperationStatus;Device;ipaddress;MonitorStatus;Event_OID_numeric;Event_Name;Category;Variable_Bindings" />
  <consolidation id="4" name="SYSLOG"
  criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent" />
  <consolidation id="1" name="SYSTEM"
  criteria="OperationStatus;Device;MonitorStatus;ApplicationType;TextMessage" />
</consolidations>

See Appendix A for examples of usage with Curl
See Appendix B and Appendix C for example query data in both XML and JSON:
  Response Data - XML - JSON

14.2 Create or Update Consolidations

Persist a batch (1..n) of consolidations in foundation database. Consolidation records will be created if they do not exist. If a consolidation exists, it will be updated.

If one or more consolidation creation operations fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Consolidation creation/update operation is returned back in the resultset described below with a status of success or failure.

14.2.1 Method: POST

POST /api/consolidations

14.2.2 HTTP Headers

14.2.3 Post Data Attributes and Elements

14.2.4 XML POST Data Example

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<consolidations>
   <consolidation name='VEMA' criteria='MonitorStatus;ApplicationType'/>
   <consolidation name='BMS' criteria='Device;ApplicationType'/>
</consolidations>

More Post Data Examples: XML - JSON

14.2.5 HTTP Status Codes

200 - Zero or more consolidations were created without any internal server errors
500 - An internal server error occurred

14.2.6 Example Response

In this example, we use the POST data above. Two consolidations were successfully created.

Note that the results collection also returns the location of the created or updated consolidation which can be directly used by the GET operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Consolidation"
             operation="Update" warning="0" count="2">
  <result>
    <entity>VEMA</entity>
    <location>http://localhost/api/consolidations/VEMA</location>
    <status>success</status>
  </result>
  <result>
    <entity>BMS</entity>
    <location>http://localhost/api/consolidations/BMS</location>
    <status>success</status>
  </result>
</results>

14.3 Delete Consolidations

Deletes one or more consolidations from the Collage database.

14.3.1 Method: DELETE

DELETE /api/consolidations/name1

where name1 is the name of the consolidation to delete

DELETE /api/consolidations/name1,name2 ...
A comma-separated list of two consolidation names (or more) are provided. Note that no-spaces are allowed in this HTTP path segment.

14.3.2 HTTP Headers

14.3.3 HTTP Status Codes

200 - Consolidation records were deleted successfully
500 - An internal server error occurred

14.3.4 Example Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="Consolidation"
             operation="Delete" warning="0" count="2">
  <result>
    <entity>name1</entity>
    <message>Consolidation deleted</message>
    <status>success</status>
  </result>
  <result>
    <entity>name2</entity>
    <message>Consolidation deleted</message>
    <status>success</status>
  </result>
</results>

15.0 Notification APIs

(top)

15.1 Create Host Notifications

Send a batch (1..n) of host NOMA notifications to GroundWork server.

If one or more notification messages fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual notification message is returned back in the resultset described below with a status of success or failure.

15.1.1 Method: POST

POST /api/notifications/hosts

15.1.2 HTTP Headers

15.1.3 Post Data Attributes and Elements

15.1.4 XML POST Data Example

<notifications>
   <notification
   	      hostName='server-12'
   	      hostAddress='10.0.0.11'
   	      hostGroupNames='group-21,group-22'
   	      hostNotificationId=''
   	      hostOutput='Hypervisor cannot be reached to determine the status'
   	      hostState='PENDING'
   	      notificationComment='Cloud Hub Host Notification'
   	      notificationRecipients=''
   	      notificationType='RECOVERY'
   	      checkDateTime='2014-04-14 07:21:'
   	      notificationAuthOrAlias=''
   />
</notifications>

See Appendix A for examples of usage with Curl
More Post Data Examples: XML - JSON

15.1.5 HTTP Status Codes

200 - Zero or more notifications were created without any internal server errors
500 - An internal server error occurred

15.1.6 Example Response

In this example, we use the POST data above. Two host notifications were successfully created.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="HostNotification"
       operation="Update" warning="0" count="2">
  <result>
    <entity>server-12</entity>
    <message></message>
    <status>success</status>
  </result>
  <result>
    <entity>server-13</entity>
    <message></message>
    <status>success</status>
  </result>
</results>

15.2 Create Service Notifications

Send a batch (1..n) of service NOMA notifications to GroundWork server.

If one or more notification messages fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual notification message is returned back in the resultset described below with a status of success or failure.

15.2.1 Method: POST

POST /api/notifications/services

15.2.2 HTTP Headers

15.2.3 Post Data Attributes and Elements

15.2.4 XML POST Data Example

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<notifications>
    <notification
              hostName='server-12'
              serviceDescription='local_cpu_nagios'
              hostAddress='10.0.0.11'
              hostGroupNames='group-21,group-22'
              hostAlias='host1'
              serviceGroupNames='sg1,sg2'
              serviceOutput='Service cannot be reached to determine the status'
              serviceState='UNKNOWN'
              serviceNotificationId='433'
              notificationComment='Cloud Hub Host Notification'
              notificationRecipients='admin@gwos.com'
              notificationType='RECOVERY'
              checkDateTime='2014-04-14 07:21:33'
              notificationAuthOrAlias='alias'
     />
 /notifications>

See Appendix A for examples of usage with Curl
More Post Data Examples: XML - JSON

15.2.5 HTTP Status Codes

200 - Zero or more notifications were created without any internal server errors
500 - An internal server error occurred

15.2.6 Example Response

In this example, we use the POST data above. Two service notifications were successfully created.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="ServiceNotification"
       operation="Update" warning="0" count="2">
  <result>
    <entity>server-12:local_cpu_nagios</entity>
    <message></message>
    <status>success</status>
  </result>
  <result>
    <entity>service-13:vm.cpu_util</entity>
    <message></message>
    <status>success</status>
  </result>
</results>

16.0 Performance Data APIs

(top)

16.1 Create Perf Data

Send a batch (1..n) of Performance Data records to the GroundWork Server

If one or more Perf Data messages fails, others may still succeed. This is not an all-or-none transactional operation. The results of each individual Perf Data message is returned back in the resultset described below with a status of success or failure.

16.1.1 Method: POST

POST /api/perfdata

16.1.2 HTTP Headers

16.1.3 Post Data Attributes and Elements

16.1.4 XML POST Data Example

<perfDataList>
   <perfData
        appType='OS'
        label='CPU Utilized'
        serverName='localhost'
        serverTime='1397512737'
        serviceName='vm.cpu_util'
        value='65'
        critical='95'
        warning='85'
    />
</perfDataList>

See Appendix A for examples of usage with Curl
More Post Data Examples: XML - JSON

16.1.5 HTTP Status Codes

200 - Zero or more notifications were created without any internal server errors
500 - An internal server error occurred

16.1.6 Example Response

In this example, we use the POST data above. Two Perf Data records were successfully created.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<results successful="2" failed="0" entityType="PerfData"
         operation="Update" warning="0" count="2">
  <result>
    <entity>OS - localhost:vm.cpu_util</entity>
    <message>OK</message>
    <status>success</status>
  </result>
  <result>
    <entity>OS - localhost:host.free_ram_mb</entity>
    <message>OK</message>
    <status>success</status>
  </result>
</results>

16.2 Get Time Series Performance Data

Gets proxied time series from underlying performance data store. Data returned includes host/service values and thresholds for a specific time range. This service is primarily intended to drive graphing in the Status viewer and thus is not a generalized graph query endpoint. It's intended to return raw data posted to the performance data endpoint, (see 16.1 above). Outside of down sampling to return data in the specified interval, aggregation or other transformations cannot be performed. Returned performance data captures query parameters in a wrapping XML <perfDataTimeSeries> element or JSON object with a perfDataTimeSeriesValues array member.

Direct retrieval from RRD files via this API is not supported and will result in no results. However, if the underlying performance data store is configured to be RRD, then retrieval of performance data is possible if performance data is also being stored in Foundation by way of configuring /usr/local/groundwork/config/perfdata.properties. See the send_perf_data property in the <foundation> section for more details. This is not generally recommended unless you are using BIRT Performance (EPR) reports.

16.2.1 Method: GET Performance Data

GET /api/perfdata?(query parameters)

16.2.2 HTTP Query and Path Parameters

16.2.3 HTTP Headers

16.2.4 Examples

These examples are not HTTP encoded for readability. In practice queries must be encoded.

1. time series data for a service
   GET /api/perfdata?serverName=loadtest-vm-0&serviceName=loadtest-vm-metric-0&startTime=1443160800000&endTime=1443207330000&interval=72000

16.2.5 HTTP Status Codes

16.2.6 Example Time Series Data

Here is an XML example of returned time series performance data. Value types returned can include the value, thold-c, (critical threshold), and thold-w, (warning threshold).

XML query results are always wrapped in an <perfDataTimeSeries> collection element, with one or more <perfDataTimeSeriesValue> subelements.

<perfDataTimeSeries appType="VEMA" serverName="loadtest-vm-0" serviceName="loadtest-vm-metric-0" startTime="1443208066000" endTime="1443208366000" interval="30000">
    <perfDataTimeSeriesValue valueType="value" timestamp="1443208110000" value="36.0"/>
    <perfDataTimeSeriesValue valueType="value" timestamp="1443208170000" value="27.0"/>
    <perfDataTimeSeriesValue valueType="value" timestamp="1443208230000" value="20.0"/>
    <perfDataTimeSeriesValue valueType="value" timestamp="1443208290000" value="13.0"/>
    <perfDataTimeSeriesValue valueType="thold-c" timestamp="1443208110000" value="100.0"/>
    <perfDataTimeSeriesValue valueType="thold-c" timestamp="1443208170000" value="100.0"/>
    <perfDataTimeSeriesValue valueType="thold-c" timestamp="1443208230000" value="100.0"/>
    <perfDataTimeSeriesValue valueType="thold-c" timestamp="1443208290000" value="100.0"/>
    <perfDataTimeSeriesValue valueType="thold-w" timestamp="1443208110000" value="90.0"/>
    <perfDataTimeSeriesValue valueType="thold-w" timestamp="1443208170000" value="90.0"/>
    <perfDataTimeSeriesValue valueType="thold-w" timestamp="1443208230000" value="90.0"/>
    <perfDataTimeSeriesValue valueType="thold-w" timestamp="1443208290000" value="90.0"/>
</perfDataTimeSeries>

Here is a JSON example of returned time series performance data.

JSON query results are always wrapped in an object with a perfDataTimeSeriesValues array member, with one or more object members.

{
  "appType" : "VEMA",
  "serverName" : "loadtest-vm-0",
  "serviceName" : "loadtest-vm-metric-0",
  "startTime" : 1443208066000,
  "endTime" : 1443208366000,
  "interval" : 30000,
  "perfDataTimeSeriesValues" : [ {
    "valueType" : "value",
    "timestamp" : 1443208110000,
    "value" : 36.0
  }, {
    "valueType" : "value",
    "timestamp" : 1443208170000,
    "value" : 27.0
  }, {
    "valueType" : "value",
    "timestamp" : 1443208230000,
    "value" : 20.0
  }, {
    "valueType" : "value",
    "timestamp" : 1443208290000,
    "value" : 13.0
  }, {
    "valueType" : "thold-c",
    "timestamp" : 1443208110000,
    "value" : 100.0
  }, {
    "valueType" : "thold-c",
    "timestamp" : 1443208170000,
    "value" : 100.0
  }, {
    "valueType" : "thold-c",
    "timestamp" : 1443208230000,
    "value" : 100.0
  }, {
    "valueType" : "thold-c",
    "timestamp" : 1443208290000,
    "value" : 100.0
  }, {
    "valueType" : "thold-w",
    "timestamp" : 1443208110000,
    "value" : 90.0
  }, {
    "valueType" : "thold-w",
    "timestamp" : 1443208170000,
    "value" : 90.0
  }, {
    "valueType" : "thold-w",
    "timestamp" : 1443208230000,
    "value" : 90.0
  }, {
    "valueType" : "thold-w",
    "timestamp" : 1443208290000,
    "value" : 90.0
  } ]
}

17.0 Version API

(top)

The Version API returns the current version of the REST API.

API Since: 7.0.2

Supports both XML and JSON

17.1 HTTP Headers

17.2 Method: GET Version

GET /api/version

17.3 Example Results

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<version>7.0.2</version>

{
  "version" : "7.0.2"
}