This document describes specifications of Nagira API: endpoints, HTTP methods and output.

Examples of the curl command and output are given in FEATURES file.

Supported Output formats

Output format is specified by extension at the end of the HTTP request. It can be 1 of .xml, .json or .yaml. If output specifier is absent Nagira will use default configured format (see CONFIGURATION.

Default responses

Success

Failure

For not existing routes, object not found or object not configured in Nagios, 404 is returned. At the momemnt it is impossible to distinquish between non-existing routes and non-existing object(s).

Top level routes

General information

API endpoints in General section do not provide Nagios information, they are used to receive from Nagira information related to Nagira application itself and Nagios instance Nagira talks to.

GET / (root)

Provides general information about Nagira application, no nested routes.


GET /_api

Prints out available routes on the Nagira application. No nested sub-routes.


GET /_runtime

Print runtime Nagira environment configuration. No nested sub-routes.

Available: since Nagira version > 0.2.1


Nagios server information

Nagios information section describes methods for accessing Nagios objects and status information, as well as updating status information.

GET /_config

Nagios server configuration information: location of Nagios configuration files, log files, various setting usually found in main Nagios configuration file nagios.cfg.

No nested sub routes/endpoints available.

Hash with all configuration options of Nagios server. See for example: http://nagios.sourceforge.net/docs/3_0/configmain.html All attributes are formatted exactly as they are read from nagios.cfg file without any conversions.


API Extensions

/_objects and /_status family of routes support extensions _list, _state and _full and can use of both plural and singular names of resources. Specifications below show where each one of the extensions can or can not be used.

_list,_state and _full

Either _list, _state or _full keyword can be appended to the HTTP request path at the end to modify response as:

For example:

Note: _list modifier changes output type of the request. /_status and /_object request can return either Hash or Array, depending on other parts of request (see below, plural vs singular) but _list request always returns Array.

Plural and singular resources

Nagira API up to version 0.2.1 used Nagios resources as nouns in singular form ('host', 'hostgroup', 'service', 'contact'), same way as they are used by Nagios. In order to support ActiveResource type of requests, use of pluralized resources has been added.

ActiveResource expects JSON output of search result in the form of Array, but Nagira provides results as Hash. So, in order to be ActiveResource compliant without breaking backward compatibility, following rule is used:

Where this is available following forms of request are supported:


Read Nagios objects configuration

GET /_objects

All Nagios object configurations grouped into Hash subtrees by resource type (host, service, contact, command).

List of all possible objects can be obtained from http://nagios.sourceforge.net/docs/3_0/objectdefinitions.html.

Note Only currently configured objects are listed.

GET /_objects/:type

Read object type configuration. Object types are supported by Nagios.

GET /_objects/:type/:name

Read configuration of one object.


Read host and services status

Host status and host services status

GET /_status

Get all hosts status, see Nagira#get_status

Subroutes

GET /_status/:hostname

Read hoststatus for single host, see Nagira#get_status_hostname_services

GET /_status/:hostname/_services

GET /status/:hostname/_services/:servicename

Read single services for single host. Not including host state information.

Comments

Subrotes _hostcomments and _servicecomments return comment for the host or service.

GET /status/:hostname/servicecomments

GET /status/:hostname/hostcomments


Read Servicegroup status

GET /_status/_servicegroup/:servicegroup

    { "<hostname>":
        "<servicename>" :
          { "key" : "value", ...},
          ...

$ curl localhost:4567/_status/_servicegroup/ping.yaml
---
archive:
  PING:
    host_name: archive
    service_description: PING
    modified_attributes: '0'
    check_command: check_ping!100.0,20%!500.0,60%
      ...

Extensions

_list

$ curl localhost:4567/_status/_servicegroup/ping/_list
{"archive":["PING"],
    "kurobka":["PING","SSH"],
      "airport":["PING"]
}

_state

      

Read hostgroup status

GET /_status/_hostgroup/:hostgroup

    { "<hostname>":
        "hoststatus" :
          { "key" : "value", ...},
        "servicestatus" :
        {
        "<servicename>" :
          { "key" : "value", ...},
        "gateway": {
           "hoststatus": {
             "host_name": "gateway",
             "modified_attributes": "0",
             "check_command": "check-host-alive",
             "notification_period": "_24x7",
             },
           "servicestatus": {
             "PING": {
               "host_name": "gateway",
               "service_description": "PING",
               "modified_attributes": "0",
               "check_command": "check_ping!100.0,20%!500.0,60%",
               "check_period": "_24x7",

Subroutes

GET /status/_hostgroup/:hostgroup/service

         {
           "gateway": {
             "PING": {
               "host_name": "gateway",
               "service_description": "PING",
               "modified_attributes": "0",
               "check_command": "check_ping!100.0,20%!500.0,60%",
               "check_period": "_24x7",
               "notification_period": "_24x7",
               "check_interval": "1.000000",
               "retry_interval": "1.000000",

GET /status/_hostgroup/:hostgroup/host

         {
         "gateway": {
           "host_name": "gateway",
           "modified_attributes": "0",
           "check_command": "check-host-alive",
           "notification_period": "_24x7",
           "check_interval": "5.000000",
           "retry_interval": "1.000000",
           "has_been_checked": "1",