RESTful Services

h3. Contents {anchor:Top}

This page reviews the RESTful API for GroundWork Monitor 7.0.2.

{toc:minLevel=4|maxLevel=4|printable=false}

h4. 1.0 Auth APIs

[(top)|#Top]

since: 7.0.2

h5. 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
{color:#4a86e8}&password=d3N1c2Vy&gwos-app-name=cloudhub{color}

h6. 1.1.1 Method: POST

{color:#4a86e8}POST /api/auth/login?user=d3N1c2Vy{color}

h6. 1.1.2 HTTP Query Parameters

|| Field || Description || Required ||
| user | Base64 encoded user name | yes |
| password | Base64 encoded password | yes |
| gwos-app-name | identifies your application name | yes |

*Example*

{color:#4a86e8}POST /api/auth/login?user=d3N1c2Vy&password=d3N1c2Vy&gwos-app-name=cloudhub{color}
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

h5. 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

h6. 1.2.1 Method: POST

{color:#4a86e8}POST /api/auth/logout?gwos-api-token=392393939239&gwos-app-name=cloudhub{color}

h6. 1.2.2 HTTP Query Parameters

|| Field || Description || Required ||
| gwos-api-token | The token returned from login | yes |
| gwos-app-name | identifies your application name | yes |

*Example*

{color:#4a86e8}POST /api/auth/logout?gwos-api-token=392393939239&gwos-app-name=cloudhub{color}
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

h4. 2.0 Host APIs {anchor:Host APIs}

[(top)|#Top]









h5. 2.1 Query Hosts

Retrieve hosts by query. There are two kinds of queries supported:
# Retrieving a single host. Retrieves exactly one host object wrapped by an XML {{<host>}} element
# Retrieving one or more hosts. Retrieves 1..n host objects wrapped by an XML {{<hosts>}} collection

h6. 2.1.1 Method: GET Hosts

{color:#4a86e8}GET /api/hosts?query=(query criteria see below){color}

h6. 2.1.2 Method: GET a single host by name

{color:#4a86e8}GET /api/hosts/{color}{html}{hostName}{html}

h6. 2.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| hostName | Path | the name of the host | no |
| agentId | Query | The agent id managing this host | no |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |

_If neither a hostName path parameter or query query parameter is not provided, all hosts will be retrieved_

h6. 2.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 2.1.5 Query Fields

|| Field || Description || Alias ||
| id | Host id | hostId |
| hostName | The name of the host | name \\
host |
| description | The description of this host | &nbsp; |
| appType | Application Type name short cut | applicationType.name |
| applicationType | The associated application type. Valid query fields: \\
applicationType.name \\
applicationType.description \\
applicationType.applicationTypeId \\
applicationType.stateTransitionCriteria | |
| monitorStatus | The monitor status (from host status) | monitor |
| agentId | The agent id managing this host | |
| device | The unique identification for the device associated with this host | deviceIdentification |
| deviceName | The display name of the device | deviceDisplayName |
| lastCheckTime | The timestamp for the last host check | |
| hostGroup | The name of a host group where this host is a member of | |
| stateType | The state type name | |
| checkType | The check type name | |
| properties | one or more valid dynamic property names | |

_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:

| shallow | primitive data attributes, 1:1 association names, properties (default) |
| deep | shallow, plus: associated collections (shallow), 1:1 associations shallow |
| simple | Same as shallow except there are no properties |

h6. 2.1.6 Example Queries

_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all hosts, with shallow depth_
{color:#4a86e8}GET /api/hosts{color}
# _query for all hosts, with simple depth (only basic attributes, no properties)_
{color:#4a86e8}GET /api/hosts?depth=simple{color}
# _query for all hosts, with deep depth_
{color:#4a86e8}GET /api/hosts?depth=deep{color}
# _query for a single host named localhost, with depth of shallow_
{color:#4a86e8}GET /api/hosts/localhost{color}
# _query for a single host named localhost, with depth of deep_
{color:#4a86e8}GET /api/hosts/localhost?depth=deep{color}
# _query for a single host named localhost, with depth of simple_
{color:#4a86e8}GET /api/hosts/localhost?depth=simple{color}
# _query on a single property using LIKE operator_
{color:#4a86e8}GET /api/hosts?query=property.LastPluginOutput like ‘OK%’{color}
# _query on a property using a range query, and monitor status field, order by a property_
{color:#4a86e8}GET /api/hosts?query=(property.ExecutionTime between 10 and 3500 and (monitorStatus <> 'UP')) order by property.ExecutionTime{color}
# _query on host’s lastCheckTime using date functions_
{color:#4a86e8}GET /api/hosts?query=day(lastCheckTime) = 22 and month(lastCheckTime) = 5 and minute(lastCheckTime) > 43 order by lastCheckTime{color}
# _query on two numeric properties using range queries, ordering result_
{color:#4a86e8}GET /api/hosts?query=(property.ExecutionTime < 10 and property.Latency between 800 and 900) order by property.Latency{color}

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.
{code}<?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>{code}

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

{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp; Shallow Depth Query Response Data - [XML|DOC70:RESTful Appendices#Host - Response Data - Shallow XML] \- [JSON|DOC70:RESTful Appendices#Host - Response Data - Shallow JSON]
&nbsp;&nbsp; Deep Depth Query Response Data - [XML|DOC70:RESTful Appendices#Host - Response Data - Deep XML] \- [JSON|DOC70:RESTful Appendices#Host - Response Data - Deep JSON]
&nbsp;&nbsp; Simple Depth Query Response Data - [XML|DOC70:RESTful Appendices#Host Query - Response Data - Simple Depth XML] \- [JSON|DOC70:RESTful Appendices#Host Query - Response Data - Simple JSON]












h5. 2.2 Create Hosts {anchor: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.

h6. 2.2.1 Method: POST

{color:#4a86e8}POST /api/hosts{color}

h6. 2.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 2.2.3 Request Parameters

|| Field || Description || Required ||
| async | A boolean flag to indicate whether to submit the batch of host updates asynchronously or not. Default is false. Valid values are true or false. \\
A synchronous request will not return back to your client code until the completion of processing all objects provided in the post data. Whereas an asynchronous request will submit the work to a queue, and return immediately. | False |

h6. 2.2.4 Post Data Attributes

|| Field || Description || Required ||
| hostName | The name of the host to create. Must be unique. | True |
| description | A description of the host. Dom Note : If you want a description to show up in Status Viewer, you have to use the Alias property. | False |
| monitorStatus | The monitor status. Optional, will default to PENDING if not supplied. | False |
| deviceIdentification | The name of the device for this host. Will be created if it does not already exist. | True |
| appType | The application type. Must be a valid application type. | True |
| deviceDisplayName | The name to display in UIs. | Optional |
| properties | A collection of one or more properties to create with the host | False |

h6. 2.2.5 XML POST Data Example

{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Host Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Host Post - Post Data JSON]






















h6. 2.2.6 HTTP Status Codes

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

h6. 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.
{code}<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>{code}

h5. 2.3 Delete Host

Deletes one or more hosts from Collage database. There are two methods of deletion:
# Delete without post data, passing in one or more hostnames on URL path
# Delete with post data, passing in hostnames in post data

h6. 2.3.1 Method: DELETE without POST Data

{color:#4a86e8}DELETE /api/hosts/hostName{color}

where _hostName_ is a single host name to be deleted

{color:#4a86e8}DELETE /api/hosts/hostName1,hostName2{color}
where _hostName1_,_hostName2_ is a comma-separated list of hostNames. Note that no-spaces are allowed in this HTTP path segment.

h6. 2.3.2 Method: DELETE with POST Data

{color:#4a86e8}DELETE /api/hosts{color}

The post data should be formatted like a POST payload, but the only required field is the hostName. Example:
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hosts>
<host hostName="host-100" />
<host hostName="host-101" />
</hosts>{code}

JSON, 7.0: (deprecated in 7.1)
{code}[
{ "hostName": "host-100" },
{ "hostName": "host-101" }
]{code}

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

h6. 2.3.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 2.3.4 HTTP Status Codes

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

h6. 2.3.5 Example Response
{code}<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>{code}

h4. 3.0 Host Group APIs

[(top)|#Top]









h5. 3.1 Query Host Groups

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

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

h6. 3.1.1 Method: GET HostGroups

{color:#4a86e8}GET /api/hostgroups?query=(query criteria see below){color}

h6. 3.1.2 Method: GET a single host group by name

{color:#4a86e8}GET /api/hostgroups/{color}{html}{hostGroupName}{html}

h6. 3.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| hostGroupName | Path | the name of the host group | no |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |

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

h6. 3.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 3.1.5 Query Fields

|| Field || Description || Alias ||
| id | Host group identification | hostGroupId |
| name | The name of the host group | |
| description | The description of this host group | |
| alias | An alias for this host group | |
| appType | Application Type | applicationType |
| hosts. | A prefix for the the associated hosts with this group. For example: hosts.hostName or hosts.description | |

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

h6. 3.1.6 Example Queries

_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all host groups, with shallow depth_
{color:#4a86e8}GET /api/hostgroups{color}
# _query for all host groups, with deep depth_
{color:#4a86e8}GET /api/hostgroups?depth=deep{color}
# _query for a single host group named Engineering, with depth of shallow_
{color:#4a86e8}GET /api/hostgroups/Engineering{color}
# _query for a single host group named Engineering, with depth of deep_
{color:#4a86e8}GET /api/hostgroups/Engineering?depth=deep{color}
# _query to find all host groups containing a host named ‘localhost’_
{color:#4a86e8}GET /api/hostgroups?query=hosts.hostName = 'localhost'{color}
# _a simple like query on the host group name_
{color:#4a86e8}GET /api/hostgroups?query=name like 'Eng%'{color}
# _query for one or more names using in query syntax_
{color:#4a86e8}GET /api/hostgroups?query=name in (‘Engineering’,’Support’,’IT’,’HG1’){color}

*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.
{code}<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>{code}

For queries, the hostGroup elements are wrappered in a hostGroups element.
{code}<hostGroups>
<hostGroup id="5" name="Support" alias="support" appType="NAGIOS">
...
</hostGroup>
<hostGroup id="6" name="Sales" alias="sales" appType="NAGIOS">
...
</hostGroup>
...
</hostGroups>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Shallow Response Data - [XML|DOC70:RESTful Appendices#HostGroup - Response Data - Shallow XML] \- [JSON|DOC70:RESTful Appendices#HostGroup - Response Data - Shallow JSON]
&nbsp;&nbsp;Deep Response Data - [XML|DOC70:RESTful Appendices#HostGroup - Response Data - Deep XML] \- [JSON|DOC70:RESTful Appendices#HostGroup - Response Data - Deep JSON]













h5. 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.

h6. 3.2.1 Method: POST

{color:#4a86e8}POST /api/hostgroups{color}

h6. 3.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 3.2.3 Post Data Attributes

|| Field || Description || Required ||
| name | The name of the host group | yes |
| description | The description of this host group | no |
| alias | An alias for this host group | no |
| appType | Application Type | no, defaults to NAGIOS |
| hosts | The collection of one or more hosts to add to this host group. Note these hosts must have been previously added to the system | no |

h6. 3.2.4 XML POST Data Example

{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#HostGroup Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#HostGroup Post - Post Data JSON]



















h6. 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

h6. 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.
{code}<?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>{code}

h5. 3.3 Delete Host Group

Deletes one or more host groups from the Collage database. There are two methods of deletion:
# Delete without post data, passing in one or more host group names on URL path
# Delete with post data, passing in host group names in post data

h6. 3.3.1 Method: DELETE without POST Data

{color:#4a86e8}DELETE /api/hostgroups/hostGroupName{color}

where _hostName_ is a single host group name to be deleted

{color:#4a86e8}DELETE /api/hostgroups/hostGroupName1,hostGroupName2{color}
where _hostGroupName1_,_hostGroupName2_ is a comma-separated list of host group names. Note that no-spaces are allowed in this HTTP path segment.

h6. 3.3.2 Method: DELETE with POST Data

{color:#4a86e8}DELETE /api/hostgroups{color}

The post data should be formatted like a POST payload, but the only required field is the host Group name (name). Example:
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hostGroups>
<hostGroup name="hostGroup-100” />
<hostGroup name="hostGroup-101” />
</hostGroups>{code}

h6. 3.3.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 3.3.4 HTTP Status Codes

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

h6. 3.3.5 Example Response
{code}<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>{code}

h5. 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:
# Clear without post data, passing in one or more host group names on URL path
# Clear with post data, passing in host group names in post data

h6. 3.4.1 Method: CLEAR without POST Data

{color:#4a86e8}DELETE /api/hostgroups/hostGroupName?clear=true{color}

where _hostName_ is a single host group name to be cleared

{color:#4a86e8}DELETE /api/hostgroups/hostGroupName1,hostGroupName2?clear=true{color}

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.

h6. 3.4.2 Method: CLEAR with POST Data

{color:#4a86e8}DELETE /api/hostgroups?clear=true{color}

The post data should be formatted like a POST payload, but the only required field is the host Group Name (name). Example:
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hostGroups>
<hostGroup name="hostGroup-100” />
<hostGroup name="hostGroup-101” />
</hostsGroups>{code}

h6. 3.4.3 HTTP Status Codes

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

h6. 3.4.4 Example Response
{code}<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>{code}

h4. 4.0 Service APIs {anchor:Service APIs}

[(top)|#Top]









h5. 4.1 Query Services

Retrieve services by query. There are two kinds of queries supported:
# Retrieving a single service. Retrieves exactly one service object wrapped by an XML {{<service>}} element
# Retrieving one or more services. Retrieves 1..n service objects wrapped by an XML {{<services>}} collection

h6. 4.1.1 Method: GET Services

{color:#4a86e8}GET /api/services?query=(query criteria see below){color}
{color:#4a86e8}GET /api/services?hostName{color}

Method: GET a single service by name
{color:#4a86e8}GET /api/services/{color}{html}{serviceName}{html}{color:#4a86e8}?hostName=(hostName){color}

h6. 4.1.2. HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| hostName | Query | Two usages: \\
(1) When passed with a service path param, specifies a primary key \\
the name of the host associated with this service \\
\**required when retrieving a single service \\
(2) When passed without a service path param, specifies to retrieve all services for a given hostName \\
\**not required in this case. \\
The hostName query parameter can never be combined with the query parameter | no*\* |
| serviceName | Path | the name (description) of the service to retrieve \\
\**required when retrieving a single service | no*\* |
Note: _If neither a single serviceName path parameter or query query parameter is not provided, all hosts will be retrieved._

h6. 4.1.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 4.1.4 Query Fields

|| Field || Description || Alias ||
| id | Service id | serviceStatusId |
| hostName | The name of the host associated with the service | host |
| description | The name (description) of the service | name \\
serviceDescription |
| appType | Application Type | applicationType |
| monitorStatus | The monitor status (from host status) | monitor |
| device | The unique identification for the device associated with this host | deviceIdentification |
| deviceName | The display name of the device | deviceDisplayName |
| stateType | The state type name | &nbsp; |
| checkType | | The check type name |
| lastHardState | The last hard state monitor status | |
| lastCheckTime | The timestamp for the last service check | |
| nextCheckTime | The timestamp of the next service check | |
| lastStateChange | The timestamp of the last state change | |
| hostGroup | The name of a host group where this service is a member of | |
| properties | one or more valid dynamic property names | |

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

*Non Queryable Fields*

none

h6. 4.1.5 Example Queries

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

# _query for all services_
{color:#4a86e8}GET /api/services{color}
# _query for all services for the given host name_
{color:#4a86e8}GET /api/services?hostName=localhost{color}
# _query for a single service named local_cpu_httpd under a hostName of localhost_
{color:#4a86e8}GET /api/services/local_cpu_httpd?hostName=localhost{color}
# _query on a single property using LIKE operator_
{color:#4a86e8}GET /api/services?query=property.LastPluginOutput like ‘OK%’{color}
# _query on a property using a range query, and monitor status field, order by a property_
{color:#4a86e8}GET /api/services?query=(property.ExecutionTime between 10 and 3500 and (monitorStatus <> 'UP')) order by property.ExecutionTime{color}
# _query on service’s lastCheckTime using date functions_
{color:#4a86e8}GET /api/services?query=day(lastCheckTime) = 22 and month(lastCheckTime) = 5 and minute(lastCheckTime) > 43 order by lastCheckTime{color}
# _query on joined attributes_
{color:#4a86e8}GET /api/services?query=stateType = 'HARD' and checkType = 'ACTIVE' and lastHardState = 'PENDING' and monitorStatus = 'OK'{color}

*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.
{code}<?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>{code}

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.
{code}<?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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Distinct Response Data - [XML|DOC70:RESTful Appendices#Services - Response Data - XML] \- [JSON|DOC70:RESTful Appendices#Services - Response Data - JSON]
&nbsp;&nbsp;Query Response Data - [XML|DOC70:RESTful Appendices#Services Query - Response Data - XML] \- [JSON|DOC70:RESTful Appendices#Services Query - Response Data - JSON]
















h5. 4.2 Create Services {anchor: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.

h6. 4.2.1 Method: POST

{color:#4a86e8}POST /api/services{color}

h6. 4.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 4.2.3 Request Parameters

|| Field || Description || Required ||
| async | A boolean flag to indicate whether to submit the batch of host updates asynchronously or not. Default is false. Valid values are true or false. \\
A synchronous request will not return back to your client code until the completion of processing all objects provided in the post data. Whereas an asynchronous request will submit the work to a queue, and return immediately. | False |

h6. 4.2.4 Post Data Attributes

|| Field || Description || Required for Insert || Required for Update ||
| description | The description and identification of the service to be created or updated | True | True |
| hostName | The name host to associate to this service | True | True |
| deviceIdentification | The name of the device for this host. This field is required for insert if the host to which the new service is to be associated does not already exist. But if that host does already exist, then this field is not required. | (See Description) \\ | False |
| appType | The application type. Must be a valid application type. | True | False |
| monitorStatus | The monitor status. | True | True |
| lastStateChange | The last time stamp the service changed state | False | False |
| lastCheckTime | The last time stamp that a check on this service occurred | False | False |
| nextCheckTime | The next scheduled check time for this service | False | False |
| stateType | A valid state type such as HARD, SOFT | False | False |
| checkType | A valid check type such as ACTIVE, PASSIVE | False | False |
| lastHardState | A second monitor status. | True | False |
| properties | A collection of one or more properties to create with the service | False | False |

h6. 4.2.5 XML POST Data Example
{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Host Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Host Post - Post Data JSON]
















h6. 4.2.6 HTTP Status Codes

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

h6. 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.
{code}<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>{code}

h5. 4.3 Delete Service

Deletes one or more services form Collage database. There are two methods of deletion:
# Delete without post data, passing in one or more services on URL path
# Delete with post data, passing in service names (descriptoins in post data
_Note that a hostName query parameter is always required for deletes._

h6. 4.3.1 Method: DELETE without POST Data

{color:#4a86e8}DELETE /api/services/service-101,service-102?hostName=localhost{color}

h6. 4.3.2 Method: DELETE with POST Data

{color:#4a86e8}DELETE /api/services{color}

The post data should be formatted like a POST payload, but the only required fields are the description and hostName. Example:
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<services>
<service description="service-100” hostName="localhost” />
<service description="service-102” hostName=”localhost” />
</services>{code}

h6. 4.3.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 4.3.4 HTTP Status Codes

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

h6. 4.3.5 Example Response
{code}<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>{code}

h4. 5.0 Event APIs {anchor:Event APIs}

[(top)|#Top]









h5. 5.1 Query Events

Retrieve events by query

h6. 5.1.1 Method: GET

{color:#4a86e8}GET /api/events?query=(query criteria see below){color}

h6. 5.1.2 Method: GET with event ids

{color:#4a86e8}GET /api/events/101,204,307{color}

h6. 5.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | yes*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| eventIds | Path | comma separated list of 1..n event ids | yes*\* |
Note: _\**Query and eventIds are mutually exclusive. Both cannot be provided, but one or the other is required._

h6. 5.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.1.5 Query Fields

|| Field || Description || Alias ||
| id | Event id | logMessageId |
| appType | Application Type | applicationType |
| category | The category name | category.name |
| component | The component name | &nbsp; |
| device | The device identification | deviceName |
| host | The name of the host | hostName |
| hostGroup | The name of a host group | |
| monitor | The monitor status | monitorStatus |
| msgCount | The message count for this event | count |
| operation | The operation status | operationStatus |
| priority | The priority of the event | |
| service | The service status description | serviceDescription \\
serviceStatus |
| serviceGroup | The service group (category) for this event | category |
| severity | The severity of the event | &nbsp; |
| applicationSeverity | The application severity | appSeverity |
| statisticsType | | |
| textMessage | The event message string | message |
| typeRule | The type rule for the event | |
| | | |
| lastInsertDate | Last time this event was updated | |
| firstInsertDate | First time this event was updated | |
| reportDate | The date this event was reported | |
| | | |
| properties | one or more valid dynamic property names | |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._

h6. 5.1.6 Example Queries

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

# _query on two fields, and sort by report date_
{color:#4a86e8}GET /api/events?query=(appType='NAGIOS' and service=’http_alive’ and reportDate > '2013-06-01') order by reportDate{color}
# _query on two attributes and order by none-queried field_
{color:#4a86e8}GET /api/events?query=device = '172.28.113.156' and severity = 'CRITICAL' order by operationStatus{color}
# _Paging parameters first and count ..._
{color:#4a86e8}GET /api/events?query=service='http_alive'&first=20&count=10{color}
# _query on all text messages starting with a prefix using LIKE operator_
{color:#4a86e8}GET /api/events?query=message like 'TCP OK%'{color}
# _query on a property and field using LIKE operator_
{color:#4a86e8}GET /api/events?query=(property.SubComponent like 'localhost%' and property.ErrorType = 'SERVICE ALERT'){color}
# _query on the messsage Count greater than 2 messages_
{color:#4a86e8}GET /api/events?query=count > 2{color}
# _query on a not null field_
{color:#4a86e8}GET /api/events?query=appType is not null{color}
# _Query using appType and last insert date between a date range_
{color:#4a86e8}GET /api/events?query=(appType='NAGIOS' and service='http_alive'{color}
{color:#4a86e8}and lastInsertDate between '2013-02-01' and '2013-04-01'){color}
# _Query with a property greater than a threshold, and use a between range query on report date_
{color:#4a86e8}GET /api/events?query=(property.ExecutionTime > 800{color}
{color:#4a86e8}and (reportDate between '2013-02-01' and '2013-04-01')){color}
# _Query with a property greater than a threshold, and use a between range query on report date_
{color:#4a86e8}GET /api/events?query=(property.ExecutionTime > 800){color}
# _Range query using IN operator_
{color:#4a86e8}GET /api/events?query=host in ('qa-load-xp-1','qa-sles-11-64','do-win7-1'){color}
# _Query on hostgroup using IN operator_
{color:#4a86e8}GET /api/events?query=hostgroup in ('IT','HG1'){color}
# _Query by category_
{color:#4a86e8}GET /api/events?query=category = 'SG1'{color}
# _Query on service group using IN operator_
{color:#4a86e8}GET /api/events?query=(serviceGroup in ('web-svr','SG1')){color}
# _Query on service group and host group using IN operator_
{color:#4a86e8}GET /api/events?query=(serviceGroup in ('web-svr','SG1') and hostgroup in ('IT','HG1')){color}
# _Retrieve a single event by event id_
{color:#4a86e8}GET /api/events?104{color}
# _Retrieve a list of comma-separated events by id_
{color:#4a86e8}GET /api/events?104,207,306,494,507{color}

*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.
{code}<?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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Shallow Distinct Response Data - [XML|DOC70:RESTful Appendices#Events Query - Response Data - XML] \- [JSON|DOC70:RESTful Appendices#Events Query - Response Data - JSON]












h5. 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.

h6. 5.2.1 Method: POST

{color:#4a86e8}POST /api/events{color}

h6. 5.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.2.3 Required Post Data Attributes

|| Field || Description || Required ||
| host | The name of the host (Alias: hostName) | True \\ |
| monitorServer | The monitor server to store | True |
| appType | The application type (must be a valid application type) | True |
| textMessage | The event message | True |
| monitorStatus | The monitor status | True |
| severity | The severity of the event | True |
| consolidation \\
Name | The consolidation name to be used to build the consolidation criteria to minimize event logging | Recommended |
| device | The name of the device for this host (will be created if it does not already exist) | True |
| reportDate | The date this event was reported | True \\ |

h6. 5.2.4 Optional Post Data Attributes

|| Field || Description || Alias ||
| id | Event id | logMessageId |
| category | The category name | category.name |
| component | The component name | &nbsp; |
| hostGroup | The name of a host group | |
| msgCount | The message count for this event | count |
| operation | The operation status | operationStatus |
| priority | The priority of the event | &nbsp; |
| service | The service status description | serviceDescription \\
serviceStatus |
| serviceGroup | The service group (category) for this event | category |
| applicationSeverity | The application severity | appSeverity |
| statisticsType | &nbsp; | &nbsp; |
| typeRule | The type rule for the event | |
| lastInsertDate | Last time this event was updated | |
| firstInsertDate | First time this event was updated | |
| properties | one or more valid dynamic property names | |

h6. 5.2.5 HTTP Status Codes

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

h6. 5.2.6 Example Response
{code}<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>{code}

h6. 5.2.7 Example Post Data

The post data should be formatted like in either XML or JSON:
{code}{ "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"
}
}
]
}{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Events Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Events Post - Post Data JSON]












h5. 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).

h6. 5.3.1 Method: POST

{color:#4a86e8}POST /api/events/ack{color}

h6. 5.3.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.3.3 Required Post Data Attributes

|| Field || Description || Required ||
| appType | The application type for this event. | True |
| hostName | The host name to be matched for updating of events | True |
| serviceDescription | The name of the service to update events for | False |
| acknowledgedBy | The name of the program or user acknowledging | False |
| acknowledgeComment | Additional comments | False |

h6. 5.3.4 HTTP Status Codes

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

h6. 5.3.5 Example Post Data

The post data should be formatted in XML or JSON:
{code}<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"
}
]
}{code}

h6. 5.3.6 Example Response
{code}{
"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
}{code}

h5. 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).

h6. 5.4.1 Method: POST

{color:#4a86e8}POST /api/events/unack{color}

h6. 5.4.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.4.3 Required Post Data Attributes

|| Field || Description || Required ||
| appType | The application type for this event. | True |
| hostName | The host name to be matched for updating of events | True |
| serviceDescription | The name of the service to update events for | False |

h6. 5.4.4 HTTP Status Codes

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

h6. 5.4.5 Example Post Data

The post data should be formatted in XML or JSON:
{code}<unacks>
<unack
appType="VEMA"
hostName="STOR-datastore1"
serviceDescription="summary.freeSpace"
/>
</unacks>

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

h6. 5.4.6 Example Response
{code}{
"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
}{code}

h5. 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.

h6. 5.5.1 Method: PUT

{color:#4a86e8}PUT /api/events{color}

h6. 5.5.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
&nbsp;&nbsp; Post Data Example: [XML|DOC70:RESTful Appendices#Events Properties Update - Put Data XML] \- [JSON|DOC70:RESTful Appendices#Events Properties Update - Put Data JSON]














h6. 5.5.3 Required PUT Data

|| Field || Description || Required ||
| id | The id for this event. | True |
| properties | The set of properties to be updated on this event | True |

h6. 5.5.4 XML PUT Data Example

{color:#4a86e8}PUT /api/events/{color}

h6. 5.5.5 HTTP Status Codes

200 - Events were created or updated successfully
500 - An internal server error occurred
{code}<?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>{code}

{code}{ "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"
}
}
]
}{code}

h6. 5.5.6 Example Response
{code}<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>{code}

h5. 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.

h6. 5.6.1 Method: DELETE

{color:#4a86e8}DELETE /api/events/1,2,3{color}

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

h6. 5.6.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.6.3 XML DELETE Data Example

# Delete 3 events
{color:#4a86e8}DELETE /api/events/50,51,52{color}

h6. 5.6.4 HTTP Status Codes

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

h6. 5.6.5 Example Response
{code}<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>{code}

h5. 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.

h6. 5.6.1 Method: PUT

{color:#4a86e8}PUT /api/events/1,2,3?opStatus=NOTIFIED{color}

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

h6. 5.6.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 5.6.3 Query Parameters on PUT

|| Field || Description || Required ||
| opStatus | The operational Status to update | &nbsp; |
| updatedBy | The username who updated | True |
| comments | Comments for this event | &nbsp; |

h6. 5.7.4 XML PUT Data Example

# PUT a new operation status for three events
{color:#4a86e8}PUT /api/events/50,51,52?opStatus=NOTIFIED&updatedBy=admin&comments=testing+123{color}

h6. 5.7.5 HTTP Status Codes

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

h6. 5.7.6 Example Response
{code}<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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Events Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Events Post - Post Data JSON]









h4. 6.0 Devices APIs

[(top)|#Top]









h5. 6.1 Query Devices

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

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

h6. 6.1.1 Method: GET Device

{color:#4a86e8}GET /api/devices?query=(query criteria see below){color}

h6. 6.1.2 Method: GET a single device by identification

{color:#4a86e8}GET /api/devices/{color}{html}{deviceIdentification}{html}

h6. 6.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| deviceIdentification | Path | the identification of the device (name) | no \*\* |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |
_Note: \**If neither a deviceIdentification path parameter or query query parameter is not provided, all devices will be retrieved._

h6. 6.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 6.1.5 Query Fields

|| Field || Description || Alias ||
| id | Device integer id | deviceId |
| identification | The device primary unique name | device |
| description | The description of this device | &nbsp; |
| displayName | The name to display in UIs | name |
| hosts. | A prefix for the the associated hosts with this device. For example: hosts.hostName or hosts.description | &nbsp; |
| server | The monitor server name | monitorServer.monitorServerName |
| ip | The monitor server ip | monitorServer.ip |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._

h6. 6.1.6 Example Queries

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

# _query for all devices, with shallow depth_
{color:#4a86e8}GET /api/devices{color}
# _query for all devices, with deep depth_
{color:#4a86e8}GET /api/devices?depth=deep{color}
# _query for a single device identified by 127.0.0.1, with depth of shallow_
{color:#4a86e8}GET /api/devices/127.0.0.1{color}
# _query for a single device identified by 127.0.0.1, with depth of deep_
{color:#4a86e8}GET /api/devices/127.0.0.1?depth=deep{color}
# _a like query to find all devices starting with identification of 172.28.113.\* and filter by host name_
{color:#4a86e8}GET /api/devices?query=identification like '172.28.113%' and d.hosts.hostName = 'qa-sles-11-64-2'{color}
# _a simple or query on the display names ordered by name (displayName)_
{color:#4a86e8}GET /api/devices?query=displayName = 'demo' or displayName = 'malbec' order by name{color}
# _query for one or more display Names using in query syntax_
{color:#4a86e8}GET /api/devices?query=name in ('demo','malbec','sql-2008','127.0.0.1''){color}

*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.
{code}<device id="1"
identification="127.0.0.1"
displayName="127.0.0.1"
description="Device localhost"/>{code}

Result of queries are always wrapped in a {{<devices>}} collection element, with one or more {{<device>}} subelements.
{code}<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>{code}

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

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Shallow Response Data - [XML|DOC70:RESTful Appendices#Devices - Response Data - Shallow XML] \- [JSON|DOC70:RESTful Appendices#Devices - Response Data - Shallow JSON]
&nbsp;&nbsp;Deep Response Data - [XML|DOC70:RESTful Appendices#Devices - Response Data - Deep XML] \- [JSON|DOC70:RESTful Appendices#Devices - Response Data - Deep JSON]














h5. 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.

h6. 6.2.1 Method: POST

{color:#4a86e8}POST /api/devices{color}

h6. 6.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 6.2.3 Post Data Attributes and Elements

|| Field || Description || Required ||
| identification | The unique device identification | Yes |
| displayName | The display name of the device | &nbsp; |
| description | The description of this device | &nbsp; |
| hosts | The element wrapper (collection) of one or more hosts to add to this device. Note these hosts will be auto-created if they do not exist | &nbsp; |

h6. 6.2.4 XML POST Data Example
{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Devices Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Devices Post - Post Data JSON]














h6. 6.2.5 HTTP Status Codes

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

h6. 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.
{code}<?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>{code}

h5. 6.3 Delete Devices

Deletes one or more devices from the Collage database. There are two methods of deletion:
# Delete without post data, passing in one or more devices names on URL path
# Delete with post data, passing in device identifications in post data

h6. 6.3.1 Method: DELETE without POST Data

{color:#4a86e8}DELETE /api/devices/127.0.0.1{color}

where _127.0.0.1_ is a single device identification to be deleted

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

h6. 6.3.2 Method: DELETE with POST Data

{color:#4a86e8}DELETE /api/devices{color}

The post data should be formatted like a POST payload, but the only required field is the device Identification. Example:
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<devices>
<device identification="172.28.113.166” />
<device identification="172.28.113.168” />
</devics>{code}

h6. 6.3.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 6.3.4 HTTP Status Codes

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

h6. 6.3.5 Example Response
{code}<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>{code}

h4. 7.0 Statistics APIs

[(top)|#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

h5. 7.1 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h5. 7.2 Total Statistics

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

# Host Total Statistics
# 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.

h6. 7.2.1 Method: GET Total Statistics for Hosts

{color:#4a86e8}GET /api/statistics/totals/hosts{color}

h6. 7.2.2 Method: GET Total Statistics for Services

{color:#4a86e8}GET /api/statistics/totals/services{color}

h6. 7.2.3 Example Queries

# _query for total statistics by hosts_
{color:#4a86e8}GET /api/statistics/totals/hosts{color}
{code}<?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>{code}
# _query for total statistics by services_
{color:#4a86e8}GET /api/statistics/totals/services{color}
{code}<?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>{code}

h5. 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").

h6. 7.3.1 Method: GET Statistics by Host for Specified Hosts

{color:#4a86e8}GET /api/statistics/hosts/{color}{html}{one or more comma separated host names}{html}

h6. 7.3.2 Example Queries

# _query for statistics for the five given host names_
{color:#4a86e8}GET /api/statistics/hosts/localhost,172.28.113.151,demo,malbec,qa-load-xp-1{color}
{code}<?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>{code}

h5. 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

h6. 7.4.1 Method: GET Statistics for all host groups

{color:#4a86e8}GET /api/statistics/hostgroups{color}

h6. 7.4.2 Method: GET Statistics for a list of host groups

{color:#4a86e8}GET /api/statistics/hostgroups/{color}{html}{one or more comma-separated host group names}{html}

h6. 7.4.3 Example Queries

# _query statistics for all host groups_
{color:#4a86e8}GET /api/statistics/hostsgroups{color}
{code}<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>{code}
# _query statistics for one or more host groups comma separated_
{color:#4a86e8}GET /api/statistics/hostsgroups/Linux+Servers,Engineering{color}
{code}<?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>{code}

h5. 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:
# a list of all Host Groups (no filtering)
# filter by a list of Hosts
# filter by a list of Host Groups
# filter by a list of Service Groups

h6. 7.5.1 Method: GET All Service Statistics Grouped by Host Groups

{color:#4a86e8}GET /api/statistics/services{color}

h6. 7.5.2 Method: GET Service Statistics Filtered by Hosts

{color:#4a86e8}GET /api/statistics/services/hosts/{color}{html}{comma separated list of host names}{html}

h6. 7.5.3 Method: GET Service Statistics Filtered by Host Groups

{color:#4a86e8}GET /api/statistics/services/hostgroups/{color}{html}{comma separated list of host group names}{html}

h6. 7.5.4 Method: GET Service Statistics Filtered by Service Groups

{color:#4a86e8}GET /api/statistics/services/servicegroups/{color}{html}{comma separated list of services group names}{html}

h6. 7.5.5 Method: GET All Service Statistics Grouped by Service Groups

{color:#4a86e8}GET /api/statistics/services/servicegroups{color}

h6. 7.5.6 Example GET All Service Statistics Grouped by Host Group

# query all service statistics grouped by all host groups
{color:#4a86e8}GET /api/statistics/services{color}
{code}<?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>{code}

h6. 7.5.7 Example GET Service Statistics Filtered by Hosts

# query service statistics grouped by hosts for two hosts
{color:#4a86e8}GET /api/statistics/services/hosts/localhost,support-xp-1{color}
{code}<?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>{code}

h6. 7.5.8 Example GET Service Statistics Filtered by Host Groups

# query service statistics grouped by host groups for two host groups
{color:#4a86e8}GET /api/statistics/services/hostgroups/Engineering,Linux+Servers{color}
{code}<?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>{code}

h6. 7.5.9 Example GET Service Statistics Filtered by Service Groups

# query service statistics grouped by service groups for one service group
{color:#4a86e8}GET /api/statistics/services/servicegroups/SG1{color}
{code}<?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>{code}

h6. 7.5.10 Example GET All Service Statistics Grouped by Service Groups

# query all service statistics grouped by all host groups
{color:#4a86e8}GET /api/statistics/services/servicegroups{color}
{code}<?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>{code}

h5. 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
# Host Availability by Host Group Name
# Service Availability by Host Group Name
# Service Availability by Service Group Name

h6. 7.6.1 Method: GET Host Availability by Host Group Name

{color:#4a86e8}GET /api/statistics/availability/hosts?hostGroup={color}{html}{hostGroupName}{html}

h6. 7.6.2 Method: GET Service Availability by Host Group Name

{color:#4a86e8}GET /api/statistics/availability/services?hostGroup={color}{html}{hostGroupName}{html}

h6. 7.6.3 Method: GET Service Availability by Service Group Name

{color:#4a86e8}GET /api/statistics/availability/services?serviceGroup={color}{html}{serviceGroupName}{html}

h6. 7.6.4 Example GET Host Availability by Host Group Name

{color:#4a86e8}GET /api/statistics/availability/hosts?hostGroup=Engineering{color}
{code}?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="100.0" queryBy="hosts"
queryParam="hostGroup" queryValue="HG1" />{code}

h6. 7.6.5 Example GET Service Availability by Host Group Name

{color:#4a86e8}GET /api/statistics/availability/services?hostGroup=Linux+Servers{color}
{code}<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="50.0" queryBy="services"
queryParam="hostGroup" queryValue="HG1" />{code}

h6. 7.6.6 Example GET Service Availability by Service Group Name

{color:#4a86e8}GET /api/statistics/availability/services?serviceGroup=SG1{color}
{code}<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<statistic availability="100.0" queryBy="services"
queryParam="serviceGroup" queryValue="SG1" />{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both [XML|DOC70:RESTful Appendices#Statistics - XML] and [JSON|DOC70:RESTful Appendices#Statistics - JSON]









h4. 8.0 Category APIs

[(top)|#Top]









h5. 8.1 Query Categories

Retrieve categories by query. There are two kinds of queries supported:
# Retrieving a single category. Retrieves exactly one category wrapped by an XML {{<category>}} element
# Retrieving one or more categories . Retrieves 1..n category objects wrapped by an XML {{<categories>}} collection

h6. 8.1.1 Method: GET Category

{color:#4a86e8}GET /api/categories?query=(query criteria see below){color}

h6. 8.1.2 Method: GET a single category by unique category name

{color:#4a86e8}GET /api/categories/{color}{html}{categoryName}{html}

h6. 8.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| categoryName | Path | the unique name of the category | no \*\* |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |
\*Note: \**If neither a categoryName path parameter or query query parameter is not provided, all categories will be retrieved.\_

h6. 8.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 8.1.5 Query Fields

|| Field || Description || Depth || Alias ||
| id | Category integer id | Shallow | categoryId |
| name | The category primary unique name | Shallow | &nbsp; |
| description | The description of this category | Shallow &nbsp; |
| entityTypeName | Shortcut to entityType.name | Shallow | entityType.name |
| entityType | A prefix for the associated entity type of this category. Valid queried sub-fields are: \\
entityType.name \\
entityType.entityTypeId \\
entityType.description \\
entityType.LogicalEntity \\
entityType.applicationTypeSupported | Deep | &nbsp; |
| c.categoryEntities | A prefix for the child category entities associated with this category. Valid sub-fields are: \\
c.categoryEntities.categoryEntityID \\
c.categoryEntities.objectID \\
c.categoryEntities.entityType.name \\
c.categoryEntities.entityType.entityTypeId \\
c.categoryEntities.entityType.description \\
c.categoryEntities.entityType.LogicalEntity \\
c.categoryEntities.entityType.applicationTypeSupported | Deep | |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._

h6. 8.1.6 Example Queries

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

# _query for all categories, with shallow depth_
{color:#4a86e8}GET /api/categories{color}
# _query for all categories, with deep depth, order by name descending_
{color:#4a86e8}GET /api/categories?depth=deep&query=order by name desc{color}
# _query for a single category named ‘HeavyLoad’ with depth of shallow_
{color:#4a86e8}GET /api/categories/HeavyLoad{color}
# _query for a single category named ‘TopPriority’ with depth of deep_
{color:#4a86e8}GET /api/categories/TopPriority?depth=deep{color}
# _a like query to find all categories starting with ‘SERVICE_’\_
{color:#4a86e8}GET /api/categories?query=name like 'SERVICE_%'{color}
# _query for all categories of type ‘SERVICE_GROUP’ ordered by name_
{color:#4a86e8}GET /api/categories?query=entityType.name = 'SERVICE_GROUP' order by name{color}
# _query for one or more category names using IN query syntax_
{color:#4a86e8}GET /api/categories?query=name in (‘americas’,’east-region’,’west-region’’){color}
# _query for one or more category names by object id of child collection of Category Entities_
{color:#4a86e8}GET /api/categories?query=c.categoryEntities.objectID = 22{color}

*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.
{code}<category id="2" name="SG1" description="Service Group 1"
entityTypeName="SERVICE_GROUP" />{code}

Result of queries are always wrapped in a <categories> collection element, with one or more <category> subelements.
{code}<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>{code}

The full entity type will be displayed when depth = deep. Also, category entities are displayed.
{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Shallow Response Data - [XML|DOC70:RESTful Appendices#Categories - Response Data - Shallow XML] \- [JSON|DOC70:RESTful Appendices#Categories - Response Data - Shallow JSON]
&nbsp;&nbsp;Deep Response Data - [XML|DOC70:RESTful Appendices#Categories - Response Data - Deep XML] \- [JSON|DOC70:RESTful Appendices#Categories - Response Data - Deep JSON]














h5. 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.

h6. 8.2.1 Method: POST

{color:#4a86e8}POST /api/categories{color}

h6. 8.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 8.2.3 Post Data Attributes and Elements

|| Field || Description || Required || Type ||
| name | The unique category name | Yes | Attribute |
| description | The description of this caetgory | No | Attribute |
| entityTypeName | The unique entity type name. Required to associate this category with an entity type | Yes | Attribute |
| entities | The element wrapper (collection) of one or more category entities to add to this category. Note these entities will be auto-created if they do not exist | No | Element |
| entityType | The unique entity type name. If entityTypeName attribute is not provided, entityType.name attribute is required | No | Element |

h6. 8.2.4 CategoryEntity Attributes and Elements

|| Field || Description || Required ||
| objectID | The object ID for this entity | Yes |
| entityTypeName | The unique entity type name. Required to associate this category entity with an entity type | Yes |

h6. 8.2.5 XML POST Data Example
{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Categories Post - Post Data XML] \- [JSON|DOC70:RESTful Appendices#Categories Post - Post Data JSON]














h6. 8.2.6 HTTP Status Codes

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

h6. 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.
{code}<?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>{code}

h5. 8.3 Delete Categories

Deletes one or more categories from the Collage database. There are two methods of deletion:
# Delete without post data, passing in one or more category names on URL path
# Delete with post data, passing in category names via post data

h6. 8.3.1 Method: DELETE without POST Data

{color:#4a86e8}DELETE /api/categories/west-region{color}

where _west-region_ is the name of the category to delete

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

h6. 8.3.2 Method: DELETE with POST Data

{color:#4a86e8}DELETE /api/categories{color}

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

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

h6. 8.3.3 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 8.3.4 HTTP Status Codes

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

h6. 8.3.5 Example Response
{code}<?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>{code}

h4. 9.0 Graph APIs

[(top)|#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

h5. 9.1 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h5. 9.2 Query Fields

|| Field || Description || Required ||
| hostName | Generate a graph for this hostName. Must be a valid hostname | True |
| name | The optional serviceName. If not specified, a graph will be generated for each service of the given host. | False |
| applicationType | A valid applicationType. If not provided, defaults to “NAGIOS” | False |
| startDate | Start date is the total number of seconds since Unix epoch (time in seconds since 01-01-1970). Optional parameter. If not specified, will default to 24 hours prior to now. | False |
| endDate | End date is the total number of seconds since Unix epoch (time in seconds since 01-01-1970). Optional parameter. If not specified, defaults to now. | False |
| graphWidth | The width of the graph in pixels. If not specified, defaults to 620 | False |

h5. 9.3 Method: GET Graphs

{color:#4a86e8}GET /api/graphs{color}

h5. 9.4 Example Queries

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

# _query for all services for the host named “localhost”_
{color:#4a86e8}GET /api/graphs?hostName=localhost{color}
# _query for all services for the host named localhost and service named “http_alive”_
{color:#4a86e8}GET /api/graphs?hostName=localhost&serviceName=http_alive{color}
# _query for all services for the host named “localhost”, start date = August 1, 2013_
{color:#4a86e8}GET /api/graphs?hostName=localhost&startDate=61333484400000{color}
# _query all services host named “localhost”, start date = August 1, 2013, graph width 600 pixels_
{color:#4a86e8}GET /api/graphs?hostName=localhost&startDate=61333484400000&graphWidth=600{color}

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).

h5. 9.5 Example Results
{code}<?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>{code}

h4. 10.0 Metadata APIs

[(top)|#Top]









h5. 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:
# 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]
# 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.

h6. 10.1.1 Method: GET WADL Metadata

{color:#4a86e8}GET /api/meta/wadl{color}

h6. 10.1.2 Method: GET XSD Schema Metadata

{color:#4a86e8}GET /api/meta/xsd{color}

h4. 11.0 Property Type APIs {anchor:Property Type API}

[(top)|#Top]









h5. 11.1 Query Property Types

Retrieve property types by query. There are two kinds of queries supported:
# Retrieving a single property type. Retrieves exactly one property type wrapped by an XML <propertyType
> element
# Retrieving one or more property types . Retrieves 1..n property type objects wrapped by an XML <propertyTypes> collection

h6. 11.1.1 Method: GET Property Types

{color:#4a86e8}GET /api/propertytypes?query=(query criteria see below){color}

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

{color:#4a86e8}GET /api/propertytypes/{color}{html}{propertyTypeName}{html}

h6. 11.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| propertyTypeName | Path | the unique name of the property type | no \*\* |
_Note: \**If neither a propertyTypeName path parameter or query query parameter is not provided, all propertyTypes will be retrieved._

h6. 11.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 11.1.5 Query Fields

|| Field || Description || Alias ||
| id | Property Type integer id | propertyTypeId |
| name | The property type primary unique name | |
| description | The description of this property type | &nbsp; |
| dataType | The data type of this property | \**\* |
_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:
| isBoolean = true | isInteger = true |
| isString = true | isLong = true |
| isDouble = true | &nbsp; |

h6. 11.1.6 Example Queries

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

# _query for all property types_
{color:#4a86e8}GET /api/propertytypes{color}
# _query for all property types, order by name descending_
{color:#4a86e8}GET /api/propertytypes?query=order by name desc{color}
# _query for a single propertyType named ‘ExecutionTime’_
{color:#4a86e8}GET /api/propertytypes/ExcecutionTime{color}
# _a like query to find all property types starting with ‘RRD’_
{color:#4a86e8}GET /api/propertytypes?query=name like 'RRD%'{color}
# _query for all property types of type INTEGER ordered by name_
{color:#4a86e8}GET /api/propertytypes?query=isInteger = true order by name{color}
# _query for all property types of type BOOLEAN_
{color:#4a86e8}GET /api/propertytypes?query=isBoolean = true{color}
# _query for one or more proper names using IN query syntax_
{color:#4a86e8}GET /api/propertytypes?query=name in (‘ExecutionTime’,’DeactivationTime’,’RRDCommand’’){color}

*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.
{code}<propertyType id="39" name="AcknowledgedBy" description="(none)" dataType="STRING />{code}

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more <propertyType> subelements.
{code}<propertyTypes>
<propertyType id="39" name="AcknowledgedBy" description="(none)" dataType="STRING” />
<propertyType id="29" name="ExecutionTime" description="(none)" dataType="DOUBLE” />
</propertyTypes>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Response Data - [XML|DOC70:RESTful Appendices#Property Types Query Response Data XML] \- [JSON|DOC70:RESTful Appendices#Property Types Query Response Data JSON]













h5. 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.

h6. 11.2.1 Method: POST

{color:#4a86e8}POST /api/propertytypes{color}

h6. 11.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 11.2.3 Post Data Attributes and Elements

|| Field || Description || Required || Type ||
| name | The unique property type name | Yes | Attribute |
| description | The description of this property type | No | Attribute |
| datatype | The data type name. Valid values are: \\
BOOLEAN \\
STRING \\
INTEGER \\
LONG \\
DOUBLE | Yes | Attribute |

h6. 11.2.4 XML POST Data Example
{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Property Types Post Data XML] \- [JSON|DOC70:RESTful Appendices#Property Types Post Data JSON]













h6. 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

h6. 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.
{code}<?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>{code}

h5. 11.3 Delete Property Types

Deletes one or more property types from the Collage database.

h6. 11.3.1 Method: DELETE

{color:#4a86e8}DELETE /api/propertytypes/name1{color}

where _name1_ is the name of the property type to delete

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

h6. 11.3.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 11.3.3 HTTP Status Codes

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

h6. 11.3.4 Example Response
{code}<?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>{code}

h4. 12.0 Application Type APIs {anchor:Application Type APIs}

[(top)|#Top]









h5. 12.1 Query Application Types

Retrieve application types by query. There are two kinds of queries supported:
# Retrieve a single applicationType. Retrieves exactly one applicationType wrapped XML {{<applicationType>}} element
# Retrieve one or more application types . Retrieves 1..n application type objects wrapped by an XML {{<applicationTypes>}} collection

h6. 12.1.1 Method: GET Application Types

{color:#4a86e8}GET /api/applicationtypes?query=(query criteria see below){color}

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

{color:#4a86e8}GET /api/applicationtypes/{color}{html}{applicationTypeName}{html}

h6. 12.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| applicationTypeName | Path | the unique name of the application type | no \*\* |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |
_Note: \**If neither a applicationTypeName path parameter or query query parameter is not provided, all applicationTypes will be retrieved._

h6. 12.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 12.1.5 Query Fields

|| Field || Description || Alias ||
| id | Application Type integer id | applicationTypeId |
| name | The application type primary unique name | &nbsp; |
| description | The description of this application type | &nbsp; |
| stateTransitionCriteria | Comma separated list of state transition criteria | &nbsp; |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._

h6. 12.1.6 Example Queries

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

# _query for all application types_
{color:#4a86e8}GET /api/applicationtypes{color}
# _query for all application types, order by name descending_
{color:#4a86e8}GET /api/applicationtypes?query=order by name desc{color}
# _query for a single applicationType named ‘NAGIOS’_
{color:#4a86e8}GET /api/applicationtypes/NAGIOS{color}
# _a like query to find all application types in list_
{color:#4a86e8}GET /api/applicationtypes?query=name in ('SYSTEM','SNMPTRAP','SYSLOG'){color}

*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:
# entityProperties
# entityTypes
# any capitalized property
{code}<applicationType id="200" name="VEMA"
description="Virtual Environment Monitor Agent"
stateTransitionCriteria="Device;Host;ServiceDescription">
<properties>
....
</properties>
<entityProperties>
...
</entityProperties>
<entityTypes>
...
</entityTypes>
</applicationType>{code}
Result of queries are always wrapped in a <applicationTypes> collection element, with one or more <applicationType> subelements.
{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Response Data - [XML|DOC70:RESTful Appendices#Application Types Query Response Data XML] \- [JSON|DOC70:RESTful Appendices#Application Types Query Response Data JSON]













h5. 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.
{code}<entityProperty>
<entityType>HOST_STATUS</entityType>
<propertyType>isAcknowledged</propertyType>
<sortOrder>52</sortOrder>
</entityProperty>{code}

h6. 12.2.1 Method: POST

{color:#4a86e8}POST /api/applicationtypes{color}

h6. 12.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 12.2.3 Post Data Attributes and Elements

|| Field || Description || Required || Type ||
| name | The unique application type name | Yes | Attribute |
| description | The description of this application type | No | Attribute |
| stateTransitionCriteria | comma-separated list of transition criteria | Yes | ttribute |
| entityProperties | A list of entityProperties defining the valid entityTypes and propertyTypes for this applicationType. An optional sort order can also be provided. | No | Attribute |

h6. 12.2.4 XML POST Data Example
{code}<?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>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Application Types Post Data XML] \- [JSON|DOC70:RESTful Appendices#Application Types Post Data JSON]













h6. 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

h6. 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.
{code}<?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>{code}

h5. 12.3 Delete Application Types

Deletes one or more application types from the Collage database.

h6. 12.3.1 Method: DELETE

{color:#4a86e8}DELETE /api/applicationtypes/name1{color}

where _name1_ is the name of the application type to delete

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

h6. 12.3.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 12.3.3 HTTP Status Codes

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

h6. 12.3.4 Example Response
{code}<?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>{code}

h4. 13.0 Entity Type APIs

[(top)|#Top]









h5. 13.1 Query Entity Types

Retrieve entity types by query. There are two kinds of queries supported:
# Retrieve a single entityType. Retrieves exactly one entityType wrapped XML <entityType> element
# Retrieve one or more entity types . Retrieves 1..n entity type objects wrapped by an XML <entityTypes> collection

h6. 13.2 Method: GET Entity Types

{color:#4a86e8}GET /api/entitytypes?query=(query criteria see below){color}

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

{color:#4a86e8}GET /api/entitytypes/{color}{html}{entityTypeName}{html}

h6. 13.4 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| entityTypeName | Path | the unique name of the entity type | no \*\* |
_Note: \**If neither a entityType path parameter or query query parameter is not provided, all entityTypes will be retrieved._

h6. 13.5 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 13.6 Query Fields

|| Field || Description || Alias ||
| id | Entity Type integer id | entityTypeId |
| name | The entity type primary unique name | &nbsp; |
| description | The description of this property type | &nbsp; |
| isLogicalEntity | Boolean flag set if a logical entity | &nbsp; |
| applicationTypeSupported | Boolean flag for application type support | &nbsp; |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._
\***The fields entity

h6. 13.7 Example Queries

_These examples are not HTTP encoded for readability. In practice queries must be encoded._
# _query for all entity types_
{color:#4a86e8}GET /api/entitytypes{color}
# _query for all entity types, order by name descending_
{color:#4a86e8}GET /api/entitytypes?query=order by name desc{color}
# _query for a single entityType named ‘DEVICE’_
{color:#4a86e8}GET /api/entitytypes/DEVICE{color}
# _a like query to find all entity types in list_
{color:#4a86e8}GET /api/entitytypes?query=name in (‘DEVICE','HOST,'CATEGORY){color}

*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.
{code}<entityType id="15" name="STATE_TYPE"
description="com.groundwork.collage.model.impl.StateType"
isLogicalEntity="false" applicationTypeSupported="false" />{code}

Result of queries are always wrapped in a <propertyTypes> collection element, with one or more {{<propertyType>}} subelements.
{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Response Data - [XML|DOC70:RESTful Appendices#Entity Types Query Response Data XML] \- [JSON|DOC70:RESTful Appendices#Entity Types Query Response Data JSON]









h4. 14.0 Consolidation APIs

[(top)|#Top]









h5. 14.1 Query Consolidations

Retrieve consolidations by query. There are two kinds of queries supported:
# Retrieve a single consolidation. Retrieves exactly one consolidation wrapped XML {{<consolidation>}} element
# Retrieve one or more consolidations . Retrieves 1..n consolidation objects wrapped by an XML {{<consolidations>}} collection

h6. 14.1.1 Method: GET Consolidations

{color:#4a86e8}GET /api/consolidations?query=(query criteria see below){color}

h6. 14.1.2 Method: GET a single Consolidation by unique consolidation name

{color:#4a86e8}GET /api/consolidations/{color}{html}{consolidationName}{html}

h6. 14.1.3 HTTP Query and Path Parameters

|| Field || Type || Description || Required ||
| query | Query | An encoded query string (where clause) | no \*\* |
| first | Query | Paging. First record to start from | no |
| count | Query | Paging. Number of records to include when paging | no |
| consolidationName | Path | the unique name of the consolidation criteria | no \*\* |
| depth | Query | The depth of the response data. Either ‘shallow’ or ‘deep’. Defaults to shallow | no |
_Note: \**If neither a consolidationName path parameter or query query parameter is not provided, all consolidations will be retrieved._

h6. 14.1.4 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 14.1.5 Query Fields

|| Field || Description || Alias ||
| id | Consolidation integer id | consolidationId |
| name | The consolidation primary unique name | &nbsp; |
| criteria | Semi-colon separated list of consolidation criteria | &nbsp; |
_Note: Query fields are case-insensitive, thus camelCase, or all lower case will both work fine._
\***The fields entity

h6. 14.1.6 Example Queries

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

# _query for all consolidations_
{color:#4a86e8}GET /api/consolidations{color}
# _query for all consolidations, order by name descending_
{color:#4a86e8}GET /api/consolidations?query=order by name desc{color}
# _query for a single consolidation named 'SYSTEM'_
{color:#4a86e8}GET /api/consolidations/SYSTEM{color}
# _a like query to find all consolidations in list_
{color:#4a86e8}GET /api/consolidations?query=like 'SY%'{color}

*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.
{code}<consolidation id="4" name="SYSLOG"
criteria="OperationStatus;Device;MonitorStatus;ipaddress;ErrorType;SubComponent"/>{code}

Result of queries are always wrapped in a {{<propertyTypes>}} collection element, with one or more {{<propertyType>}} subelements.
{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
See [Appendix B|DOC70:RESTful Appendices#Appendix B XML Example Data] and [Appendix C|DOC70:RESTful Appendices#Appendix C JSON Example Data] for example query data in both XML and JSON:
&nbsp;&nbsp;Response Data - [XML|DOC70:RESTful Appendices#Consolidation Query Response Data XML] \- [JSON|DOC70:RESTful Appendices#Consolidation Query Response Data JSON]













h5. 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.

h6. 14.2.1 Method: POST

{color:#4a86e8}POST /api/consolidations{color}

h6. 14.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME y | our application name | True |

h6. 14.2.3 Post Data Attributes and Elements

|| Field || Description || Required || Type ||
| name | The unique consolidation name | Yes | Attribute |
| criteria | Semi-colon separated list of consolidation criteria | Yes | Attribute |

h6. 14.2.4 XML POST Data Example
{code}<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<consolidations>
<consolidation name='VEMA' criteria='MonitorStatus;ApplicationType'/>
<consolidation name='BMS' criteria='Device;ApplicationType'/>
</consolidations>{code}

More Post Data Examples: [XML|DOC70:RESTful Appendices#Consolidation Post Data Data XML] \- [JSON|DOC70:RESTful Appendices#Consolidation Post Data Data JSON]













h6. 14.2.5 HTTP Status Codes

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

h6. 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.
{code}<?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>{code}

h5. 14.3 Delete Consolidations

Deletes one or more consolidations from the Collage database.

h6. 14.3.1 Method: DELETE

{color:#4a86e8}DELETE /api/consolidations/name1{color}

where _name1_ is the name of the consolidation to delete

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

h6. 14.3.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 14.3.3 HTTP Status Codes

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

h6. 14.3.4 Example Response
{code}<?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>{code}

h4. 15.0 Notification APIs

[(top)|#Top]









h5. 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.

h6. 15.1.1 Method: POST

{color:#4a86e8}POST /api/notifications/hosts{color}

h6. 15.1.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 15.1.3 Post Data Attributes and Elements

|| Field || Description || Required ||
| hostState | A valid Host Monitor Status such as UP, UNREACHABLE, WARNING, PENDING, UNSCHEDULED DOWN, SCHEDULED DOWN, DOWN | Yes |
| hostName | the name of the host | Yes |
| hostGroupNames | a comma-separated list of one or more valid host group names | No |
| notificationType | A valid Notification type such as RECOVERY or PROBLEM | Yes |
| hostAddress | the IP address of the host | No |
| hostOutput | the textual output to be sent to the notification server | Yes |
| checkDateTime | a time stamp in YYYY-MM-DD hh:mm:ss format | No |
| hostNotificationId | | No |
| notificationAuthOrAlias | &nbsp; | No |
| notificationComment | Additional comments | No |
| notificationRecipients | | No |

h6. 15.1.4 XML POST Data Example
{code}<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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
More Post Data Examples: [XML|DOC70:RESTful Appendices#Consolidation Post Data Data XML] \- [JSON|DOC70:RESTful Appendices#Consolidation Post Data Data JSON]













h6. 15.1.5 HTTP Status Codes

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

h6. 15.1.6 Example Response

In this example, we use the POST data above. Two host notifications were successfully created.
{code}<?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>{code}

h5. 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.

h6. 15.2.1 Method: POST

{color:#4a86e8}POST /api/notifications/services{color}

h6. 15.2.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 15.2.3 Post Data Attributes and Elements

|| Field || Description || Required ||
| serviceState | A valid Service Status such as WARNING, OK, UNKNOWN, UNSCHEDULED CRITICAL, PENDING_SERVICE, SCHEDULED CRITICAL | Yes |
| hostName | The name of the host | Yes |
| hostGroupNames | a comma-separated list of one or more valid Host Group names | No |
| serviceGroupNames | a comma-separated list of one or more valid Service Group names | No |
| serviceDescription | the name (description) of the service | Yes |
| serviceOutput | the textual output to be sent to the notification server | Yes |
| notificationType | A valid Notification type such as RECOVERY or PROBLEM | Yes |
| hostAlias | | No |
| hostAddress | the IP address of the host | No |
| checkDateTime | a time stamp in YYYY-MM-DD hh:mm:ss format | No |
| serviceNotificationId | | No |
| notificationAuthOrAlias | &nbsp; | No |
| notificationComment | Additional comments | No |
| notificationRecipients | | No |

h6. 15.2.4 XML POST Data Example
{code}<?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>{code}

See [Appendix A|DOC70:RESTful Appendices#Appendix A Curl Examples] for examples of usage with Curl
More Post Data Examples: [XML|DOC70:RESTful Appendices#Service Notification POST Data XML] \- [JSON|DOC70:RESTful Appendices#Service Notification POST Data JSON]













h6. 15.2.5 HTTP Status Codes

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

h6. 15.2.6 Example Response

In this example, we use the POST data above. Two service notifications were successfully created.
{code}<?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>{code}

h4. 16.0 Performance Data APIs

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.

h6. 16.1.1 Method: POST

{color:#4a86e8}POST /api/perfdata{color}

h6. 16.1.2 HTTP Headers

|| Header || Valid Values || Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h6. 16.1.3 Post Data Attributes and Elements

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

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

h6. 16.1.6 Example Response

In this example, we use the POST data above. Two Perf Data records were successfully created.
{code}<?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>

[(top)|#Top]









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

API Since: 7.0.2

Supports both XML and JSON

h5. 17.1 HTTP Headers

|| Header || Valid Values | Required ||
| Content-Type | application/xml or application/json | True |
| GWOS-API-TOKEN | a valid token returned from login | True |
| GWOS-APP-NAME | your application name | True |

h5. 17.2 Method: GET Version

{color:#4a86e8}GET /api/version{color}

h5. 17.3 Example Results
{code}<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<version>7.0.2</version>

{
"version" : "7.0.2"
}{code}