WAS THIS PAGE HELPFUL? {html}<a href="mailto:training@gwos.com?subject=Biz Downtime APIs">Leave Feedback</a>{html}
h4. 20.0 Biz APIs
h5. 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 | \- |
h6. {color:#333333}20.1.1 Method: POST Set In Downtime{color}
{color:#4a86e8}POST /api/biz/setindowntime{color}
h6. {color:#333333}20.1.2 POST Data Example{color}
Here is an XML example post data setting a service in downtime:
{code: language=html/xml}
<bizHostsAndServices>
<hostNames>
<hostName>localhost</hostName>
</hostNames>
<serviceDescriptions>
<serviceDescription>local_memory</serviceDescription>
</serviceDescriptions>
</bizHostsAndServices>
{code}
Here is an XML example of post data setting all services and hosts for a host group in downtime:
{code: language=html/xml}
<bizHostsAndServices>
<hostNames>
<hostName>*</hostName>
</hostNames>
<serviceDescriptions>
<serviceDescription>*</serviceDescription>
</serviceDescriptions>
<serviceGroupCategoryNames>
<serviceGroupCategoryName>Linux Services</serviceGroupCategoryName>
</serviceGroupCategoryNames>
</bizHostsAndServices>
{code}
Here is a JSON example post data setting all services for two hosts in downtime:
{code: language=javascript}
{
"hostNames" : [ "host0", "host1" ],
"serviceDescriptions" : [ "*" ]
}
{code}
Here is a JSON example of post data setting hosts for host groups in downtime:
{code: language=javascript}
{
"hostNames" : [ "*" ],
"hostGroupNames" : [ "HG1", "HG2" ]
}
{code}
h6. {color:#333333}20.1.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.1.4 HTTP Status Codes{color}
|| 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 |
h6. {color:#333333}20.1.5 Example Results{color}
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.
{code: language=html/xml}
<bizHostServiceInDowntimes>
<bizHostServiceInDowntime hostName="localhost" serviceDescription="local_memory" scheduledDowntimeDepth="0" entityType="SERVICE_STATUS" entityName="local_memory"/>
</bizHostServiceInDowntimes>
{code}
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.
{code: language=javascript}
{
"bizHostServiceInDowntimes" : [ {
"hostName" : "host0",
"scheduledDowntimeDepth" : 1,
"entityType" : "HOSTGROUP",
"entityName" : "Linux Servers"
}, {
"hostName" : "host1",
"scheduledDowntimeDepth" : 1,
"entityType" : "HOSTGROUP",
"entityName" : "Linux Servers"
} ]
}
{code}
h5. {color:#333333}20.2 Clear Hosts and Services In Downtime{color}
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.
h6. {color:#333333}20.2.1 Method: POST Clear In Downtime{color}
{color:#4a86e8}POST /api/biz/clearindowntime{color}
h6. {color:#333333}20.2.2 POST Data Example{color}
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.
h6. {color:#333333}20.2.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.2.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Specified hosts and services cleared downtime |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host blacklists |
h6. {color:#333333}20.2.5 Example Results{color}
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.
h5. {color:#333333}20.3 Get Hosts and Services In Downtime{color}
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.
h6. {color:#333333}20.3.1 Method: POST Get In Downtime{color}
{color:#4a86e8}POST /api/biz/getindowntime{color}
h6. {color:#333333}20.3.2 POST Data Example{color}
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.
h6. {color:#333333}20.3.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.3.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Specified hosts and services downtime retrieved |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host blacklists |
h6. {color:#333333}20.3.5 Example Results{color}
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.
h4. 20.0 Biz APIs
h5. 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 | \- |
h6. {color:#333333}20.1.1 Method: POST Set In Downtime{color}
{color:#4a86e8}POST /api/biz/setindowntime{color}
h6. {color:#333333}20.1.2 POST Data Example{color}
Here is an XML example post data setting a service in downtime:
{code: language=html/xml}
<bizHostsAndServices>
<hostNames>
<hostName>localhost</hostName>
</hostNames>
<serviceDescriptions>
<serviceDescription>local_memory</serviceDescription>
</serviceDescriptions>
</bizHostsAndServices>
{code}
Here is an XML example of post data setting all services and hosts for a host group in downtime:
{code: language=html/xml}
<bizHostsAndServices>
<hostNames>
<hostName>*</hostName>
</hostNames>
<serviceDescriptions>
<serviceDescription>*</serviceDescription>
</serviceDescriptions>
<serviceGroupCategoryNames>
<serviceGroupCategoryName>Linux Services</serviceGroupCategoryName>
</serviceGroupCategoryNames>
</bizHostsAndServices>
{code}
Here is a JSON example post data setting all services for two hosts in downtime:
{code: language=javascript}
{
"hostNames" : [ "host0", "host1" ],
"serviceDescriptions" : [ "*" ]
}
{code}
Here is a JSON example of post data setting hosts for host groups in downtime:
{code: language=javascript}
{
"hostNames" : [ "*" ],
"hostGroupNames" : [ "HG1", "HG2" ]
}
{code}
h6. {color:#333333}20.1.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.1.4 HTTP Status Codes{color}
|| 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 |
h6. {color:#333333}20.1.5 Example Results{color}
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.
{code: language=html/xml}
<bizHostServiceInDowntimes>
<bizHostServiceInDowntime hostName="localhost" serviceDescription="local_memory" scheduledDowntimeDepth="0" entityType="SERVICE_STATUS" entityName="local_memory"/>
</bizHostServiceInDowntimes>
{code}
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.
{code: language=javascript}
{
"bizHostServiceInDowntimes" : [ {
"hostName" : "host0",
"scheduledDowntimeDepth" : 1,
"entityType" : "HOSTGROUP",
"entityName" : "Linux Servers"
}, {
"hostName" : "host1",
"scheduledDowntimeDepth" : 1,
"entityType" : "HOSTGROUP",
"entityName" : "Linux Servers"
} ]
}
{code}
h5. {color:#333333}20.2 Clear Hosts and Services In Downtime{color}
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.
h6. {color:#333333}20.2.1 Method: POST Clear In Downtime{color}
{color:#4a86e8}POST /api/biz/clearindowntime{color}
h6. {color:#333333}20.2.2 POST Data Example{color}
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.
h6. {color:#333333}20.2.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.2.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Specified hosts and services cleared downtime |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host blacklists |
h6. {color:#333333}20.2.5 Example Results{color}
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.
h5. {color:#333333}20.3 Get Hosts and Services In Downtime{color}
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.
h6. {color:#333333}20.3.1 Method: POST Get In Downtime{color}
{color:#4a86e8}POST /api/biz/getindowntime{color}
h6. {color:#333333}20.3.2 POST Data Example{color}
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.
h6. {color:#333333}20.3.3 HTTP Headers{color}
|| 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 |
h6. {color:#333333}20.3.4 HTTP Status Codes{color}
|| Code || Description ||
| 200 | Specified hosts and services downtime retrieved |
| 401 | Authentication/authorization error occurred |
| 500 | An internal server error occurred while querying host blacklists |
h6. {color:#333333}20.3.5 Example Results{color}
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.