Using the Nagios XI API

The built-in Nagios XI API (Application Programming Interface) provides access to a wide range of data, including hosts, services, users, and more. There are times when you may need to interact with the API. To do that you need to learn how to access the API as well as what it contains.

What is contained in the API

The Nagios XI API is divided into three core sections: Objects, Config, and System. Each section serves a distinct purpose, making the API highly flexible and powerful.

Objects: This section is read-only and provides detailed information about various elements within Nagios XI. It allows users to query important resources, such as hosts, services, and other objects, providing insight into their current states and configurations. The data retrieved from this section can be delivered in either XML or JSON formats, making it easy to integrate and process within other applications or systems.

Config: The Config section is designed for administrative tasks, giving administrators the ability to add, remove, and modify objects such as hosts, services, and other configurations within Nagios XI. This section works directly with the Core Config Manager, allowing the creation and deletion of items. It provides a more dynamic role within the API, as it enables direct management and updates of system configurations to meet specific needs or changes in the infrastructure.

System: Like the Config section, the System section is reserved for administrators and provides the ability to manage the core subsystems of Nagios XI. It allows admins to execute system-level commands, configure system settings, and perform administrative tasks that impact the overall functionality and health of the Nagios XI environment.

How to Access the API

The Nagios XI API can be accessed in a similar way to how you interact with Nagios XI itself—using a web browser. To begin, enter the following URL in your browser:

http://<Your Nagios XI IP>/nagiosxi/api/v1/

At this point, you’ll see an error message—this is expected since no requests have been made yet. To retrieve data, you need to specify the section of the API you want to query and the resource you’re interested in. The URL should look like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>

The section refers to a main area of the API, like objects, config, or system, each offering access to different data or functions. For example, the objects section retrieves information about items like hosts and services, while the config section allows administrators to manage those objects. A resource is a specific data type or object within that section that you query or manipulate. In the objects section, a resource might be hoststatus, showing the current status of hosts, while in the config section, a resource could be service, used to manage service configurations.

To access the API, you’ll also need to include your API key in the URL. This key grants you access to the system and helps determine the permissions you have based on your user role. Depending on your level of access, different sections and resources may be available to you.

To find your API key, navigate to the admin section of Nagios XI. Once you have it, append it to the URL like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>?apikey=<API key>

With everything set up correctly, you should now see real data returned from the API. We’ll use the results from querying hoststatus objects as an example.

By default, the output can appear a bit messy. To improve readability, you can check the Pretty-print checkbox in the UI, which automatically organizes the response. Alternatively, append &pretty=1 to the end of the URL for instant formatting. This makes the output clean, organized, and easy to digest.

http://<Your Nagios XI IP>/nagiosxi/api/v1/objects/hoststatus?apikey=<API key>&pretty=1

Objects are for displaying information while config and system are for adding, removing or modifying objects, what you have to write differs depending on what you want to do with the API, but you should be able to do all that using a similar process. You will receive a message if it succeeds or end up with an error.

Using with Code

There are many reasons why you might want to access the Nagios XI API programmatically. For instance, you may want to fetch the data posted to the system, monitor host/service statuses, or edit configurations directly through your code. Interacting with the API via code provides flexibility and automation, streamlining your workflow.

To access the API, we can use the appropriate method for interacting with URLs in the programming language you’re working with. Since Nagios XI runs on a web-based interface, the most common language for writing programs inside Nagios XI itself is PHP.

Below is an example of how to access and interact with the Nagios XI API using PHP:

<?php
// Define the server IP and API token
$server_ip = '<Your Nagios XI IP>';  // Replace with your Nagios XI IP
$api_token = '<Your API Key>';  // Replace with your Nagios XI API key

// Build the URL for the API request
$url = "http://$server_ip/nagiosxi/api/v1/<section>/<resource>?apikey=$api_token&pretty=1";

// Initialize cURL session
$ch = curl_init();

// Set the URL for the request
curl_setopt($ch, CURLOPT_URL, $url);

// Set option to return the response as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the request and store the response
$response = curl_exec($ch);

// Check if the request was successful
if ($response === false) {
    echo "Error: " . curl_error($ch);  // Handle errors if the request fails
} else {
    // Decode the JSON response
    $data = json_decode($response, true);
    
    // Output the response (for testing or processing)
    echo "<pre>";
    print_r($data);  // Print the data in a readable format
    echo "</pre>";
}

// Close the cURL session
curl_close($ch);
?>

This code example demonstrates how to send a request to the API, process the response, and display the data in a readable format. It’s a simple and efficient way to automate interactions with Nagios XI.

Conclusion

The Nagios XI API is a powerful tool for managing your Nagios XI instance, offering programmatic access to key data and configuration management capabilities. By following the steps outlined here, you can quickly integrate the API into your processes, improving your workflow. Whether you’re querying status data, managing configurations, or integrating with other systems, the Nagios XI API gives you the flexibility to enhance your Nagios XI experience.

For additional assistance, be sure to check the Nagios XI help section for more in-depth resources and support regarding the API.