Nagios XI API Question

[ciaranrh]

Hello,

I've been searching through and am unable to find anything detailing the full list GET requests that can made against the NagiosXI API. For example,

Code: Select all

curl -XGET http://nagiosxi.****.net/nagiosxi/api/v1/objects/hoststatus?apikey=h6i6aikcjjvpf6oudjae6mne3oqabujr232bjjk64ktinlf49mgec7rcsjl7f60h&pretty=1

will return a list of host status's in human readable interface as requested with the 'pretty=1' in the GET request. Are there any others available that can be used for object references?

What I'm hoping is that there is one to specify a reporting period for the JSON data returned. As far as I can tell the returned JSON data goes back as far as the server itself.

Appreciate any thoughts on the topic

[Box293]

No official documentation that I know of.

As far the example you provided, hoststatus will return one object per host, so I don't see how it could be restricted by date, unless perhaps you wanted to see objects that had a last_check of xxxx.

As far as I'm aware, you can use any value displayed in the output. For example:

https://xitest.box293.local/nagiosxi/ap ... zz-zzz-zzz

Returns just one host.

I could not determine a way to filter that was a "like" instead of an exact match.

However some objects are ignored like:

&normal_check_interval=5

We'll see what the devs have to say.

FYI, if you wanted to look at the code.
In the file /usr/local/nagiosxi/html/api/includes/utils-api.inc.php this case:

Code: Select all

                    case 'hoststatus':
                        $data = get_host_status_xml_output($this->request);
                        return xml2json::transformXmlStringToJson($data);
                        break;

Calls the function get_host_status_xml_output which is defined in the file /usr/local/nagiosxi/html/includes/utils-xmlstatus.inc.php which may shed some light onto what is happening.

[ciaranrh]

Here's what the function function get_host_status_xml_output in /usr/local/nagiosxi/html/includes/utils-xmlstatus.inc.php has:

Code: Select all

function get_host_status_xml_output($request_args)
{
    global $sqlquery;
    global $db_tables;

    $output = "";

    $totals = grab_array_var($request_args, 'totals', false);

    // generate query
    $fieldmap = array(
        "name" => "obj1.name1",
        "host_name" => "obj1.name1",
        "display_name" => $db_tables[DB_NDOUTILS]["hosts"] . ".display_name",
        "address" => $db_tables[DB_NDOUTILS]["hosts"] . ".address",
        "alias" => $db_tables[DB_NDOUTILS]["hosts"] . ".alias",
        "instance_id" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".instance_id",
        "hoststatus_id" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".hoststatus_id",
        "host_id" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".host_object_id",
        "status_update_time" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".status_update_time",
        "current_state" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".current_state",
        "state_type" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".state_type",
        "last_check" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".last_check",
        "last_state_change" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".last_state_change",
        "modified_attributes" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".modified_host_attributes",
        "has_been_checked" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".has_been_checked",
        "active_checks_enabled" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".active_checks_enabled",
        "passive_checks_enabled" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".passive_checks_enabled",
        "notifications_enabled" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".notifications_enabled",
        "event_handler_enabled" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".event_handler_enabled",
        "is_flapping" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".is_flapping",
        "flap_detection_enabled" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".flap_detection_enabled",
        "scheduled_downtime_depth" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".scheduled_downtime_depth",
        "problem_acknowledged" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".problem_has_been_acknowledged",
        "check_command" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".check_command",
        "current_check_attempt" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".current_check_attempt",
        "max_check_attempts" => $db_tables[DB_NDOUTILS]["hoststatus"] . ".max_check_attempts",
    );
    $objectauthfields = array(
        "host_id"
    );
    $instanceauthfields = array(
        "instance_id"
    );

    //Full data or just totals?
    $q = ($totals == 1) ? $sqlquery['GetHostStatusCount'] : $sqlquery['GetHostStatus'];

    $args = array(
        "sql" => $q,
        "fieldmap" => $fieldmap,
        "objectauthfields" => $objectauthfields,
        "objectauthperms" => P_READ,
        "instanceauthfields" => $instanceauthfields,
        "useropts" => $request_args, // ADDED 12/22/09 FOR NEW NON-BACKEND CALLS
    );
    $sql = generate_sql_query(DB_NDOUTILS, $args);

    if (!isset($request_args['brevity']))
        $brevity = 0;
    else
        $brevity = $request_args['brevity'];

    if (!($rs = exec_sql_query(DB_NDOUTILS, $sql, false))) {
        //handle_backend_db_error(DB_NDOUTILS);
    } else {
        //output_backend_header();
        $output .= "<hoststatuslist>\n";

        if ($totals == 1) { //return SQL count()
            foreach ($rs as $row)
                $count = empty($row['total']) ? 0 : $row['total'];

            $output .= "  <recordcount>" . $count . "</recordcount>\n";
        } else //count full data set
            $output .= "  <recordcount>" . $rs->RecordCount() . "</recordcount>\n";


        if (!isset($request_args["totals"])) {
            while (!$rs->EOF) {

                $output .= "  <hoststatus id='" . get_xml_db_field_val($rs, 'hoststatus_id') . "'>\n";
                $output .= get_xml_db_field(2, $rs, 'instance_id');
                $output .= get_xml_db_field(2, $rs, 'host_object_id', 'host_id');
                $output .= get_xml_db_field(2, $rs, 'host_name', 'name');
                $output .= get_xml_db_field(2, $rs, 'display_name');
                $output .= get_xml_db_field(2, $rs, 'address', 'address');
                $output .= get_xml_db_field(2, $rs, 'host_alias', 'alias');
                $output .= get_xml_db_field(2, $rs, 'status_update_time');
                $output .= get_xml_db_field(2, $rs, 'output', 'status_text');
                $output .= get_xml_db_field(2, $rs, 'long_output', 'status_text_long');
                $output .= get_xml_db_field(2, $rs, 'current_state');

                if ($brevity < 1) {
                    $output .= get_xml_db_field(2, $rs, 'icon_image');
                    $output .= get_xml_db_field(2, $rs, 'icon_image_alt');
                    $output .= get_xml_db_field(2, $rs, 'perfdata', 'performance_data');
                    $output .= get_xml_db_field(2, $rs, 'should_be_scheduled');
                    $output .= get_xml_db_field(2, $rs, 'check_type');
                    $output .= get_xml_db_field(2, $rs, 'last_state_change');
                    $output .= get_xml_db_field(2, $rs, 'last_hard_state_change');
                    $output .= get_xml_db_field(2, $rs, 'last_hard_state');
                    $output .= get_xml_db_field(2, $rs, 'last_time_up');
                    $output .= get_xml_db_field(2, $rs, 'last_time_down');
                    $output .= get_xml_db_field(2, $rs, 'last_time_unreachable');
                    $output .= get_xml_db_field(2, $rs, 'last_notification');
                    $output .= get_xml_db_field(2, $rs, 'next_notification');
                    $output .= get_xml_db_field(2, $rs, 'no_more_notifications');
                    $output .= get_xml_db_field(2, $rs, 'acknowledgement_type');
                    $output .= get_xml_db_field(2, $rs, 'current_notification_number');
                    $output .= get_xml_db_field(2, $rs, 'event_handler_enabled');
                    $output .= get_xml_db_field(2, $rs, 'process_performance_data');
                    $output .= get_xml_db_field(2, $rs, 'obsess_over_host');
                    $output .= get_xml_db_field(2, $rs, 'modified_host_attributes');
                    $output .= get_xml_db_field(2, $rs, 'event_handler');
                    $output .= get_xml_db_field(2, $rs, 'check_command');
                    $output .= get_xml_db_field(2, $rs, 'normal_check_interval');
                    $output .= get_xml_db_field(2, $rs, 'retry_check_interval');
                    $output .= get_xml_db_field(2, $rs, 'check_timeperiod_object_id', 'check_timeperiod_id');
                }

                if ($brevity < 2) {
                    $output .= get_xml_db_field(2, $rs, 'has_been_checked');
                    $output .= get_xml_db_field(2, $rs, 'current_check_attempt');
                    $output .= get_xml_db_field(2, $rs, 'max_check_attempts');
                    $output .= get_xml_db_field(2, $rs, 'last_check');
                    $output .= get_xml_db_field(2, $rs, 'next_check');
                    $output .= get_xml_db_field(2, $rs, 'state_type');
                    $output .= get_xml_db_field(2, $rs, 'notifications_enabled');
                    $output .= get_xml_db_field(2, $rs, 'problem_has_been_acknowledged', 'problem_acknowledged');
                    $output .= get_xml_db_field(2, $rs, 'passive_checks_enabled');
                    $output .= get_xml_db_field(2, $rs, 'active_checks_enabled');
                    $output .= get_xml_db_field(2, $rs, 'flap_detection_enabled');
                    $output .= get_xml_db_field(2, $rs, 'is_flapping');
                    $output .= get_xml_db_field(2, $rs, 'percent_state_change');
                    $output .= get_xml_db_field(2, $rs, 'latency');
                    $output .= get_xml_db_field(2, $rs, 'execution_time');
                    $output .= get_xml_db_field(2, $rs, 'scheduled_downtime_depth');
                }


                $output .= "  </hoststatus>\n";

                $rs->MoveNext();
            }
        }
        $output .= "</hoststatuslist>\n";
    }

    return $output;
}

My PHP is piss poor but it seems in utils-api.inc.php like the entirety of the GET request is dumped into the function call:

Code: Select all

$data = get_host_status_xml_output($this->request);

Somewhere in utils-xmlstatus.inc.php the GET request must be parsed, but looking under the get_host_status_xml_output function it seems like the request is fed right into the SQL query here:

Code: Select all

    $q = ($totals == 1) ? $sqlquery['GetHostStatusCount'] : $sqlquery['GetHostStatus'];

    $args = array(
        "sql" => $q,
        "fieldmap" => $fieldmap,
        "objectauthfields" => $objectauthfields,
        "objectauthperms" => P_READ,
        "instanceauthfields" => $instanceauthfields,
        "useropts" => $request_args, // ADDED 12/22/09 FOR NEW NON-BACKEND CALLS
    );
    $sql = generate_sql_query(DB_NDOUTILS, $args);

Where is the code for generate_sql_query? Or is that a more generic PHP function?

[jomann]

No worries about the PHP code, you don't need to read through it. I'm finishing documenting this right now. The documentation will be in 5.3.0 but I will give you screenshots of it here on the forums once it's finished either in the next couple hours or early tomorrow morning.

Edit: There's a few more things to document that I want to make sure are working throughout the entire API and will get this to you some time in the morning tomorrow.

[jomann]

I've updated it with what I can find, there may be a couple other options but these are the ones that I know of right now. Hopefully this can get you started.

[ciaranrh]

I've updated it with what I can find, there may be a couple other options but these are the ones that I know of right now. Hopefully this can get you started.

Jomann, thank you very much for that posting this, this is a terrific help for me. I also just figured out the starttime and endtime parameters are unix time stamps .

[mcapra]

Did you need additional assistance with this issue?

[ciaranrh]

No that's it for me, thanks!