REST API: Downtimes

URL: /rest/downtime. This requires authentication. Requires DOWNTIMESOME or DOWNTIMEALL access.

• GET - lists downtime. Default will list all downtimes. See below for filtering options
• POST - create downtime
• PUT - not implemented
• DELETE - cancels downtime (if running) or deletes (if not yet started). If no objects are selected, nothing is deleted

DOWNTIMEALL allows setting downtime to any object in Opsview.

DOWNTIMESOME allows setting of downtime to host or services based on the access object selection.

Note: You can only set downtime at the host group level with DOWNTIMEALL.

Note: If a user has access to some, but not all, services on a host and sets downtime for the host, then all services will also be marked in downtime. This means it is possible that a downtime has been set on a service by a user that does not have view access for.

Note: If a user has DOWNTIMEALL, but only VIEWSOME, the user could set downtime for objects that they cannot view.

Output of a list response:

{ summary => {
    rows => ....
    totalrows => ....
    allrows => ....
    page => ....
    totalpages => ....
    num_hosts => ....
    num_services => ....
  },
  list => [
    { started => 0,1,  # 0=not started yet, 1=started
      start_time => ...., # if started, actual start time, else scheduled start time
      scheduled_end_time => .....,
      comment => .....,
      author => .....,
      objects => {
        hosts => [
          { hostname => ...., id => ... }, 
        ],
        services => [ 
          { id => ...., hostname => ...., servicename => .... }, 
        ],
      }
    },
    ...
  ]
}

The list is ordered by scheduled start time, scheduled end time, comment data, author name.

You can filter this list based on the same parameters for filtering by service status.

Note: From Opsview 3.13.1, the format of the fields actual_start_time, scheduled_end_time, and start_time has changed to default to being epoch seconds. To have the old behaviour, use the URL parameter of format_datetime=1.

Attributes required for creating a downtimes:

• starttime - start time for downtime
• endtime - end time for downtime
• duration - jira style duration value for downtime. One of end_time or duration must be set for creation
• comment - free text comment regarding downtime

These parameters can either be specified in the URL or via input to the REST API. For instance, in perl format:

{
 starttime => ....,
 endtime => ....,
 comment => ....,
}

If the same parameters is found as input data and in the URL, the input data has priority.

The author of the downtime is taken from the user login information.

Downtime is created asynchronously, so the REST API will return as soon as the downtime submission is entered. There maybe a small delay before the downtime is listed in the database.

On successful submission of downtime, the response will be of the form:

{
 summary => { 
  num_hostgroups => ...., 
  num_hosts => ...., 
  num_services => ....,
 },
 list => {
  hostgroups => [
   { id => ..., name => ... },
  ],
  hosts => [
   { id => ..., hostname => .... },
  ],
  services => [
   { id => ..., hostname => ..., servicename => ... },
  ],
} 

This reflects the number of hostgroups, hosts and services that this downtime creation applied to.

In the event of a failure, the response will be:

{ 
 message => ..., 
 detail => ....,
}

Where message could be one of:

• Error validating downtime parameters
• No objects chosen for downtime creation (this could also appear if the user does not have access to the objects)
• Errors setting downtime - some objects may have downtime set

Deleting a downtime will occur whether or not the downtime is currently in progress.

You delete downtimes based on the list of objects passed to the REST API. This will delete all downtimes on these objects unless you add in a start time and comment parameter, in which case only downtimes that match that start time and comment will be deleted.

The response will be the same format as the creation of downtime.

URL parameters (these have to be URL parameters as DELETEs do not allow content data):

• start_time - start time of downtime. This can be in any format that setting a downtime parses. This is based on the scheduled start time
• comment - exact comment. Note, this is not the same as the comment entered when creating, as a prefix is added

Attributes required for creating or filtering based on downtimes:

• starttime - start time for downtime
• endtime - end time for downtime
• comment - free text comment regarding downtime

The author of the downtime is taken from the user login information.

The end time value can also be of a jira style format with a + prefixed to denote the duration. See format of downtime for examples.

Downtime is set against objects in Nagios® Core - hosts or services.

When setting downtime in the REST API, we can set downtime against a host group, a host or a service. You can specify these objects through URL parameters. Note that although you can specify downtime for a host group, it is stored in Nagios Core as downtime for each host and its services.

You can choose hosts or services using the same URL parameters as the status API, with the following rules:

• No parameters means that no objects are found (status API returns everything if no parameters is passed)
• Service objects will be returned if you have added a filtering on a parameter which looks for services, otherwise host objects are returned
• No errors are raised if objects are not found

Alternatively, you can search for objects using the following parameters, based on the object type you are searching for.

• hostgroups (downtime will take effect for all sub host groups):
  • hg.hostgroupid (same as hostgroupid - this parameter takes priority)
  • hg.hostgroupname (as you can have more than 1 host group with the same name in the hierarchy, this will apply for all of them)
• hosts:
  • hst.hostid (same as hostid - this parameter takes priority)
  • hst.hostname
  • hst.hostgroupid (this is only for the host group that the host belongs too - this is not based on the host group hierarchy)
  • hst.hostgroupname (only for host's hostgroup, not the hierarchy)
• services:
  • svc.serviceid (same as serviceid - this parameter takes priority)
  • svc.hs (same as hs)
  • svc.hostgroupid
  • svc.hostgroupname
  • svc.hostid
  • svc.hostname (can use % as wildcard)
  • svc.servicename (can use % as wildcard)
  • svc.keywordid
  • svc.keywordname
  • svc.servicegroupname
  • svc.servicecheckid

Note: host and services will only be found if you have the appropriate access to the object. In addition, setting or deleting downtime for host groups requires DOWNTIMEALL access.

The basic rule is that if you are searching for multiple fields of the same type of object, then the search fields are AND'd together, but multiple values of the same field are OR'd together.

Duplicated host or services are ignored. Duplicate host groups are also ignored, but as downtime is set against leaf host groups, it is possible to set the downtime twice on the same host groups.

If you request a specific object (using hg.hostgroupid, hg.hostgroupname, hst.hostname, hst.hostid, svc.hs, svc.serviceid) and that object does not exist, an error is raised:

{
 message => "Error when searching for objects",
 detail => "Cannot find host with name nosuchhost; Cannot find host with id 3",
}

In no objects are found, an error is returned:

{ message => "No objects chosen for downtime creation" }

For example, URL parameters of:

  ...?svc.hs=hostA::service1&svc.serviceid=45&svc.hostname=hostB&svc.hostname=hostC&svc.servicename=HTTP&svc.servicename=Disk:%

This would select the service hostA::service1, the service with id=45, and all services called HTTP or Disk:% on hostB or hostC.

You can specify the following URL parameters to use paging:

• rows - defaults to 50 entries in the downtimes list. Set to all to get all results
• page - defaults to 1st page

Note: Due to the SQL joins that are used and the way that the result comes back in a nested fashion, it is possible to list a downtime that misses out the related host/service objects. If you need the precise list of objects based on the downtimes, the best thing to do is search by the downtime filters (comment, start_time, end_time) and set rows=0. This should always return the correct number of objects for the particular downtime. See OPS-1505.

Downtime is set against objects and applies downwards, so if you:

• set downtime for a host group, all lower host groups and their hosts and their services will have the same downtime associated
• set downtime for a host, all its services will also have the same downtime (even if the user does not have access to the services)
• set downtime for a service, only that service will be set

The downtime for the object is set at submission time. This means that if you set downtime to a host group and then add a new host to that host group, the new host will not have downtime set. This is also true for downtime on hosts with new services added.