Adds API call to update port notes on devices. (#13834)

* Adds API call to update port notes on devices.

* Lint fixes.

* Fixes file permissions to proper values.

doc/API/Devices.md

@@ -1252,6 +1252,35 @@ Output:
 ]
 ```
 
+### `update_device_port_notes`
+
+Update a device port notes field in the devices_attrs database.
+
+Route: `/api/v0/devices/:hostname/port/:portid`
+
+- hostname can be either the device hostname or id
+- portid needs to be the port unique id (int).
+
+Input (JSON):
+- notes: The string data to populate on the port notes field.
+
+Examples:
+
+```curl
+curl -X PATCH -d '{"notes": "This port is in a scheduled maintenance with the provider."}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost/port/5
+```
+
+Output:
+
+```json
+[
+    {
+        "status": "ok",
+        "message": "Port notes field has been updated"
+    }
+]
+```
+
 ```curl
 curl -X PATCH -d '{"field": ["notes","purpose"], "data": ["This server should be kept online", "For serving web traffic"]}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices/localhost
 ```

includes/html/api_functions.inc.php

@@ -1132,6 +1132,28 @@ function get_port_stack(Illuminate\Http\Request $request)
     });
 }
 
+function update_device_port_notes(Illuminate\Http\Request $request): \Illuminate\Http\JsonResponse
+{
+    $portid = $request->route('portid');
+
+    $hostname = $request->route('hostname');
+    // use hostname as device_id if it's all digits
+    $device_id = ctype_digit($hostname) ? $hostname : getidbyname($hostname);
+
+    $data = json_decode($request->getContent(), true);
+    $field = 'notes';
+    $content = $data[$field];
+    if (empty($data)) {
+        return api_error(400, 'Port field to patch has not been supplied.');
+    }
+
+    if (set_dev_attrib($device_id, 'port_id_notes:' . $portid, $content)) {
+        return api_success_noresult(200, 'Port ' . $field . ' field has been updated');
+    } else {
+        return api_error(500, 'Port ' . $field . ' field failed to be updated');
+    }
+}
+
 function list_alert_rules(Illuminate\Http\Request $request)
 {
     $id = $request->route('id');

routes/api.php

@@ -78,6 +78,7 @@ Route::group(['prefix' => 'v0', 'namespace' => '\App\Api\Controllers'], function
         Route::get('oxidized/config/search/{searchstring}', 'LegacyApiController@search_oxidized')->name('search_oxidized');
         Route::get('oxidized/config/{device_name}', 'LegacyApiController@get_oxidized_config')->name('get_oxidized_config');
         Route::post('devicegroups', 'LegacyApiController@add_device_group')->name('add_device_group');
+        Route::patch('devices/{hostname}/port/{portid}', 'LegacyApiController@update_device_port_notes')->name('update_device_port_notes');
         Route::post('port_groups', 'LegacyApiController@add_port_group')->name('add_port_group');
         Route::post('port_groups/{port_group_id}/assign', 'LegacyApiController@assign_port_group')->name('assign_port_group');
         Route::post('port_groups/{port_group_id}/remove', 'LegacyApiController@remove_port_group')->name('remove_port_group');