Add support for a maintenance boolean in API results. (#15904)

* Add support for a maintenance boolean in API results.

If a device is under maintenance, it would be nice to see that from the
API. This can help drive other automation workflows where LibreNMS forms
a cornerstone in the management source of truth.

* Revert changes made by VSCode formatting.

* Revert two more formatting changes.

* Create a new API endpoint for GETing maintenance status.

This uses the same endpoint name as for setting a device to maintenance
but with a GET verb.

---------

Co-authored-by: Joe Clarke <jclarke@cisco.com>

doc/API/Devices.md

@@ -1102,6 +1102,31 @@ Output:
 }
 ```
 
+### `device_under_maintenance`
+
+Get the current maintenance status of a device.
+
+Route: `/api/v0/devices/:hostname/maintenance`
+
+Input:
+
+ -
+
+Example:
+
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/maintenance
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "is_under_maintenance": true
+}
+```
+
 ### `maintenance_device`
 
 Set a device into maintenance mode.

includes/html/api_functions.inc.php

@@ -538,6 +538,33 @@ function maintenance_device(Illuminate\Http\Request $request)
     }
 }
 
+function device_under_maintenance(Illuminate\Http\Request $request)
+{
+    // return whether or not a device is in an active maintenance window
+
+    $hostname = $request->route('hostname');
+
+    if (empty($hostname)) {
+        return api_error(400, 'No hostname has been provided to get maintenance status');
+    }
+
+    $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+    $model = null;
+    if ($device_id) {
+        $model = DeviceCache::get((int) $device_id);
+    }
+
+    if (! $model) {
+        return api_error(404, "Device $hostname not found");
+    }
+
+    return check_device_permission($device_id, function () use ($model) {
+        $maintenance = $model->isUnderMaintenance() ?? false;
+
+        return api_success($maintenance, 'is_under_maintenance');
+    });
+}
+
 function device_availability(Illuminate\Http\Request $request)
 {
     // return availability per device

routes/api.php

@@ -123,6 +123,7 @@ Route::prefix('v0')->namespace('\App\Api\Controllers')->group(function () {
         Route::get('{hostname}/port_stack', 'LegacyApiController@get_port_stack')->name('get_port_stack');
         Route::get('{hostname}/components', 'LegacyApiController@get_components')->name('get_components');
         Route::get('{hostname}/groups', 'LegacyApiController@get_device_groups')->name('get_device_groups_device');
+        Route::get('{hostname}/maintenance', 'LegacyApiController@device_under_maintenance')->name('device_under_maintenance');
         // consumes the route below, but passes to it when detected
         Route::get('{hostname}/ports/{ifname}', 'LegacyApiController@get_port_stats_by_port_hostname')->name('get_port_stats_by_port_hostname')->where('ifname', '.*');
         Route::get('{hostname}/ports/{ifname}/{type}', 'LegacyApiController@get_graph_by_port_hostname')->name('get_graph_by_port_hostname');