4.0 Service APIs

WAS THIS PAGE HELPFUL? Leave Feedback

4.0 Service APIs

4.1 Query Services

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

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

4.1.1 Method: GET Services

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

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

4.1.2. HTTP Query and Path Parameters

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

4.1.3 HTTP Headers

4.1.4 Query Fields

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

Non Queryable Fields

none

4.1.5 Example Queries

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

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

Example Query Results in XML

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

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

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

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

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

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

4.2 Create Services

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

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

4.2.1 Method: POST

POST /api/services

4.2.2 HTTP Headers

4.2.3 Request Parameters

4.2.4 Post Data Attributes

4.2.5 XML POST Data Example

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

More Post Data Examples: XML - JSON

4.2.6 HTTP Status Codes

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

4.2.7 Example Response

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

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

4.3 Delete Service

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

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

4.3.1 Method: DELETE without POST Data

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

4.3.2 Method: DELETE with POST Data

DELETE /api/services

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

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

4.3.3 HTTP Headers

4.3.4 HTTP Status Codes

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

4.3.5 Example Response

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

4.4 Service Description Autocomplete

Get limited number of sorted existing Service descriptions that match a specified prefix. Matching and sorting is done in a case-insensitive fashion. The special wildcard prefix '*' matches all names. Autocomplete names are updated asynchronously when Service descriptions are modified.

4.4.1 Method: GET Service Description Autocomplete

GET /api/servicegroups/autocomplete/{prefix}

4.4.2 Path Parameters

4.4.3 HTTP Headers

4.4.4 HTTP Status Codes

4.4.5 Example Responses

Here is an XML example of the autocomplete descriptions returned.

XML results are always wrapped in an <names> collection element, with one or more <name> subelements.

<names>
    <name>local_cpu_httpd</name>
    <name>local_cpu_java</name>
</names>

Here is a JSON example of the autocomplete descriptions returned.

JSON results are always wrapped in an object with a names array member, with one or more name strings.

{
  "names" : [ "local_cpu_httpd", "local_cpu_java" ]
}