diff --git a/doc/API/Devices.md b/doc/API/Devices.md index e36aa19c0956..43e0a8025c1c 100644 --- a/doc/API/Devices.md +++ b/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. diff --git a/includes/html/api_functions.inc.php b/includes/html/api_functions.inc.php index 63696b33a8f2..3ca998705829 100644 --- a/includes/html/api_functions.inc.php +++ b/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 diff --git a/routes/api.php b/routes/api.php index 90e8769b42ea..f687bef8b25c 100644 --- a/routes/api.php +++ b/routes/api.php @@ -123,6 +123,7 @@ 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');