20.0 Biz Downtime APIs

WAS THIS PAGE HELPFUL? Leave Feedback

20.0 Biz APIs

20.1 Set Hosts and Services In Downtime

Set downtime for hosts and services associated with host names, service descriptions, host group names, or service group names by incrementing their Nagios ScheduledDowntimeDepth properties. Hosts may be set to a single * wildcard to specify all hosts for a service(s). Similarly, service descriptions may be set to a single * wildcard to specify all services for a host(s). The following table documents the valid parameter combinations. START_DOWNTIME and IN_DOWNTIME events are also generated by this endpoint. A list of hosts and services that have been put in downtime is returned and is wrapped in an XML <bizHostServiceInDowntimes> element or JSON object with an bizHostServiceInDowntimes array member.

Hosts Services Hostgroups Servicegroups Result Nagios
* * * <empty> NOT VALID -
* * <empty> <empty> NOT VALID -
* <empty> <empty> <empty> NOT VALID -
<empty> <empty> <empty> <empty> NOT VALID -
* * HostGroupA <empty> All Hosts and Services on given Hostgroup SCHEDULE_HOSTGROUP_HOST_DOWNTIME SCHEDULE_HOSTGROUP_SVC_DOWNTIME
* <empty> HostGroupA <empty> All Hosts on given Hostgroup SCHEDULE_HOSTGROUP_HOST_DOWNTIME
<empty> * HostGroupA <empty> All Services on given Hostgroup SCHEDULE_HOSTGROUP_SVC_DOWNTIME
<empty> <empty> HostGroupA <empty> NOT VALID -
hostA * <empty> <empty> All Services for a given Host SCHEDULE_HOST_SVC_DOWNTIME
hostA <empty> <empty> <empty> Given Host SCHEDULE_HOST_DOWNTIME
hostA serviceA <empty> <empty> Given Service SCHEDULE_SVC_DOWNTIME
* * <empty> ServiceGroupA All Hosts and Services on given Servicegroup SCHEDULE_SERVICEGROUP_SVC_DOWNTIME SCHEDULE_SERVICEGROUP_HOST_DOWNTIME
* <empty> <empty> ServiceGroupA All Hosts on given Servicegroup SCHEDULE_SERVICEGROUP_HOST_DOWNTIME
<empty> * <empty> ServiceGroupA All Services on given Servicegroup SCHEDULE_SERVICEGROUP_SVC_DOWNTIME
<empty> <empty> <empty> ServiceGroupA NOT VALID -
20.1.1 Method: POST Set In Downtime

POST /api/biz/setindowntime

20.1.2 POST Data Example

Here is an XML example post data setting a service in downtime:

<bizHostsAndServices>
  <hostNames>
    <hostName>localhost</hostName>
  </hostNames>
  <serviceDescriptions>
    <serviceDescription>local_memory</serviceDescription>
  </serviceDescriptions>
</bizHostsAndServices>

Here is an XML example of post data setting all services and hosts for a host group in downtime:

<bizHostsAndServices>
  <hostNames>
    <hostName>*</hostName>
  </hostNames>
  <serviceDescriptions>
    <serviceDescription>*</serviceDescription>
  </serviceDescriptions>
  <serviceGroupCategoryNames>
    <serviceGroupCategoryName>Linux Services</serviceGroupCategoryName>
  </serviceGroupCategoryNames>
</bizHostsAndServices>

Here is a JSON example post data setting all services for two hosts in downtime:

{
  "hostNames" : [ "host0", "host1" ],
  "serviceDescriptions" : [ "*" ]
}

Here is a JSON example of post data setting hosts for host groups in downtime:

{
  "hostNames" : [ "*" ],
  "hostGroupNames" : [ "HG1", "HG2" ]
}
20.1.3 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json False
Accept application/xml or application/json False
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
20.1.4 HTTP Status Codes
Code Description
200 Specified hosts and services set in downtime
401 Authentication/authorization error occurred
500 An internal server error occurred while querying host blacklists
20.1.5 Example Results

Here is an XML example of services in downtime results. XML results are always wrapped in an <bizHostServiceInDowntimes> collection element, with one or more <bizHostServiceInDowntime> subelements.

<bizHostServiceInDowntimes>
   <bizHostServiceInDowntime hostName="localhost" serviceDescription="local_memory" scheduledDowntimeDepth="0" entityType="SERVICE_STATUS" entityName="local_memory"/>
</bizHostServiceInDowntimes>

Here is a JSON example of hosts in downtime results. JSON results are always wrapped in an object with a bizHostServiceInDowntimes array member, with one or more object elements.

{
  "bizHostServiceInDowntimes" : [ {
    "hostName" : "host0",
    "scheduledDowntimeDepth" : 1,
    "entityType" : "HOSTGROUP",
    "entityName" : "Linux Servers"
  }, {
    "hostName" : "host1",
    "scheduledDowntimeDepth" : 1,
    "entityType" : "HOSTGROUP",
    "entityName" : "Linux Servers"
  } ]
}
20.2 Clear Hosts and Services In Downtime

Clear downtime for hosts and services by decrementing their Nagios ScheduledDowntimeDepth properties. Hosts and services are specified by posting the returned in downtime list returned by the set in downtime invocation, (See 20.1). IN_DOWNTIME and CLEAR_DOWNTIME events are also generated by this endpoint. A list of hosts and services that have cleared downtime is returned and is wrapped in an XML <bizHostServiceInDowntimes> element or JSON object with an bizHostServiceInDowntimes array member.

20.2.1 Method: POST Clear In Downtime

POST /api/biz/clearindowntime

20.2.2 POST Data Example

The data posted to this endpoint must be the same returned by set in downtime, (See 20.1.5). All elements must be returned in the same order and all data fields must be preserved with the exception of the scheduledDowntimeDepth which will be overwritten.

20.2.3 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json False
Accept application/xml or application/json False
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
20.2.4 HTTP Status Codes
Code Description
200 Specified hosts and services cleared downtime
401 Authentication/authorization error occurred
500 An internal server error occurred while querying host blacklists
20.2.5 Example Results

The data returned by this endpoint will be the same as posted, (See 20.2.2 and 20.1.5). All elements will be returned in the same order and all data fields will be preserved with the exception of the scheduledDowntimeDepth which will be overwritten with the new downtime depth.

20.3 Get Hosts and Services In Downtime

Get downtime for hosts and services by returning their Nagios ScheduledDowntimeDepth properties. Hosts and services are specified by posting the returned in downtime list returned by the set in downtime invocation, (See 20.1). A list of hosts and services is returned and is wrapped in an XML <bizHostServiceInDowntimes> element or JSON object with an bizHostServiceInDowntimes array member.

20.3.1 Method: POST Get In Downtime

POST /api/biz/getindowntime

20.3.2 POST Data Example

The data posted to this endpoint will normally be the same returned by set or clear in downtime, (See 20.1.5 and 20.2.5). However, only the hostName and serviceDescription fields need to be present when posted. The scheduledDowntimeDepth fields will be overwritten with the retrieved downtime depths.

20.3.3 HTTP Headers
Header Valid Values Required
Content-Type application/xml or application/json False
Accept application/xml or application/json False
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
20.3.4 HTTP Status Codes
Code Description
200 Specified hosts and services downtime retrieved
401 Authentication/authorization error occurred
500 An internal server error occurred while querying host blacklists
20.3.5 Example Results

The data returned by this endpoint will be the same as posted, (See 20.3.2 and 20.1.5). All elements will be returned in the same order and all data fields will be preserved with the exception of the scheduledDowntimeDepth which will be overwritten with the retrieved downtime depth.