API Calls to list Device Outages, calculated Availability (#12103)

* API Calls to list Device Outages, calculated Availability

* switch to eloquent

* style correction

doc/API/Devices.md

@@ -103,6 +103,100 @@ Output:
 }
 ```
 
+### `availability`
+
+Get calculated availabilites of given device.
+
+Route: `/api/v0/devices/:hostname/availability`
+
+- hostname can be either the device hostname or id
+
+Input:
+
+  -
+
+Example:
+
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/availability
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "availability": [
+        {
+            "duration": 86400,
+            "availability_perc": "100.000000"
+        },
+        {
+            "duration": 604800,
+            "availability_perc": "100.000000"
+        },
+        {
+            "duration": 2592000,
+            "availability_perc": "99.946000"
+        },
+        {
+            "duration": 31536000,
+            "availability_perc": "99.994000"
+        }
+    ],
+    "count": 4
+}
+```
+
+### `outages`
+
+Get detected outages of given device.
+
+Route: `/api/v0/devices/:hostname/outages`
+
+- hostname can be either the device hostname or id
+
+Input:
+
+  -
+
+Example:
+
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/outages
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "outages": [
+        {
+            "going_down": 1593194031,
+            "up_again": 1593194388
+        },
+        {
+            "going_down": 1593946507,
+            "up_again": 1593946863
+        },
+        {
+            "going_down": 1594628616,
+            "up_again": 1594628968
+        },
+        {
+            "going_down": 1594628974,
+            "up_again": 1594629339
+        },
+        {
+            "going_down": 1594638668,
+            "up_again": 1594638992
+        }
+    ],
+    "count": 5
+}
+```
+
 ### `get_graphs`
 
 Get a list of available graphs for a device, this does not include ports.

includes/html/api_functions.inc.php

@@ -12,8 +12,10 @@
  * the source code distribution for details.
  */
 
+use App\Models\Availability;
 use App\Models\Device;
 use App\Models\DeviceGroup;
+use App\Models\DeviceOutage;
 use App\Models\PortsFdb;
 use App\Models\Sensor;
 use Illuminate\Database\Eloquent\Builder;
@@ -447,6 +449,48 @@ function del_device(Illuminate\Http\Request $request)
     return api_success([$device], 'devices', $response);
 }
 
+function device_availability(\Illuminate\Http\Request $request)
+{
+    // return availability per device
+
+    $hostname = $request->route('hostname');
+
+    if (empty($hostname)) {
+        return api_error(400, 'No hostname has been provided to get availability');
+    }
+
+    $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+
+    return check_device_permission($device_id, function ($device_id) {
+        $availabilities = Availability::select('duration', 'availability_perc')
+            ->where('device_id', '=', $device_id)
+            ->orderBy('duration', 'ASC');
+
+        return api_success($availabilities->get(), 'availability');
+    });
+}
+
+function device_outages(\Illuminate\Http\Request $request)
+{
+    // return outages per device
+
+    $hostname = $request->route('hostname');
+
+    if (empty($hostname)) {
+        return api_error(400, 'No hostname has been provided to get availability');
+    }
+
+    $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+
+    return check_device_permission($device_id, function ($device_id) {
+        $outages = DeviceOutage::select('going_down', 'up_again')
+            ->where('device_id', '=', $device_id)
+            ->orderBy('going_down', 'DESC');
+
+        return api_success($outages->get(), 'outages');
+    });
+}
+
 function get_vlans(Illuminate\Http\Request $request)
 {
     $hostname = $request->route('hostname');

routes/api.php

@@ -87,6 +87,8 @@ Route::group(['prefix' => 'v0', 'namespace' => '\App\Api\Controllers'], function
     Route::group(['prefix' => 'devices'], function () {
         Route::get('{hostname}', 'LegacyApiController@get_device')->name('get_device');
         Route::get('{hostname}/discover', 'LegacyApiController@trigger_device_discovery')->name('trigger_device_discovery');
+        Route::get('{hostname}/availability', 'LegacyApiController@device_availability')->name('device_availability');
+        Route::get('{hostname}/outages', 'LegacyApiController@device_outages')->name('device_outages');
         Route::get('{hostname}/graphs/health/{type}/{sensor_id?}', 'LegacyApiController@get_graph_generic_by_hostname')->name('get_health_graph');
         Route::get('{hostname}/graphs/wireless/{type}/{sensor_id?}', 'LegacyApiController@get_graph_generic_by_hostname')->name('get_wireless_graph');
         Route::get('{hostname}/vlans', 'LegacyApiController@get_vlans')->name('get_vlans');