From f3e0f3eb9383932b3bf98d230a77c1f8bef8ae39 Mon Sep 17 00:00:00 2001
From: Nick Lockhart
 <150677701+nicklockhart-fullfibre@users.noreply.github.com>
Date: Mon, 22 Jan 2024 23:07:13 +0000
Subject: [PATCH] Add port description API endpoints and documentation (#15578)

* Add port description API endpoints and documentation

* Change "update_port_description" behaviour to mimic webUI behaviour

* Fix code style issue

* Fix another code style issue
---
 doc/API/Ports.md                    | 46 ++++++++++++++++++++++++
 includes/html/api_functions.inc.php | 56 +++++++++++++++++++++++++++++
 routes/api.php                      |  2 ++
 3 files changed, 104 insertions(+)

diff --git a/doc/API/Ports.md b/doc/API/Ports.md
index 2fd624c4f2..a61ca0c998 100644
--- a/doc/API/Ports.md
+++ b/doc/API/Ports.md
@@ -379,3 +379,49 @@ Output:
   ]
 }
 ```
+
+### `get_port_description`
+
+Get the description (`ifAlias`) for a given port id.
+
+Route: `/api/v0/ports/:portid/description`
+
+Example:
+
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/ports/323/description
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "port_description": "GigabitEthernet14"
+}
+```
+
+### `update_port_description`
+
+Change the description (`ifAlias`) for a given port id.
+
+Route: `/api/v0/ports/:portid/description`
+
+Input (JSON):
+
+- description: The string data to use as the new port description.
+Sending an empty string will reset the description to default.
+
+Example:
+
+```curl
+curl -X PATCH -d '{"description": "Out-of-Band Management Link"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/ports/323/description
+```
+
+Output:
+```json
+{
+    "status": "ok",
+    "message": "Port description updated."
+}
+```
\ No newline at end of file
diff --git a/includes/html/api_functions.inc.php b/includes/html/api_functions.inc.php
index 07e8f4e4bd..a792faebdd 100644
--- a/includes/html/api_functions.inc.php
+++ b/includes/html/api_functions.inc.php
@@ -1107,6 +1107,62 @@ function get_port_info(Illuminate\Http\Request $request)
     });
 }
 
+function update_port_description(Illuminate\Http\Request $request)
+{
+    $port_id = $request->route('portid');
+    $port = Port::hasAccess(Auth::user())
+        ->where([
+            'port_id' => $port_id,
+        ])->first();
+    if (empty($port)) {
+        return api_error(400, 'Invalid port ID.');
+    }
+
+    $data = json_decode($request->getContent(), true);
+    $field = 'description';
+    $description = $data[$field];
+
+    if (empty($description)) {
+        // from update-ifalias.inc.php:
+        // "Set to repoll so we avoid using ifDescr on port poll"
+        $description = 'repoll';
+    }
+
+    $port->ifAlias = $description;
+    $port->save();
+
+    $ifName = $port->ifName;
+    $device = $port->device_id;
+
+    if ($description == 'repoll') {
+        // No description provided, clear description
+        del_dev_attrib($port, 'ifName:' . $ifName); // "port" object has required device_id
+        log_event("$ifName Port ifAlias cleared via API", $device, 'interface', 3, $port_id);
+
+        return api_success_noresult(200, 'Port description cleared.');
+    } else {
+        // Prevent poller from overwriting new description
+        set_dev_attrib($port, 'ifName:' . $ifName, 1); // see above
+        log_event("$ifName Port ifAlias set via API: $description", $device, 'interface', 3, $port_id);
+
+        return api_success_noresult(200, 'Port description updated.');
+    }
+}
+
+function get_port_description(Illuminate\Http\Request $request)
+{
+    $port_id = $request->route('portid');
+    $port = Port::hasAccess(Auth::user())
+        ->where([
+            'port_id' => $port_id,
+        ])->first();
+    if (empty($port)) {
+        return api_error(400, 'Invalid port ID.');
+    } else {
+        return api_success($port->ifAlias, 'port_description');
+    }
+}
+
 /**
  * @throws \LibreNMS\Exceptions\ApiException
  */
diff --git a/routes/api.php b/routes/api.php
index 6ee8c23f38..e2c6893ed7 100644
--- a/routes/api.php
+++ b/routes/api.php
@@ -134,6 +134,8 @@ Route::prefix('v0')->namespace('\App\Api\Controllers')->group(function () {
         Route::get('search/{field}/{search?}', 'LegacyApiController@search_ports')->name('search_ports')->where('search', '.*');
         Route::get('mac/{search}', 'LegacyApiController@search_by_mac')->name('search_mac');
         Route::get('', 'LegacyApiController@get_all_ports')->name('get_all_ports');
+        Route::get('{portid}/description', 'LegacyApiController@get_port_description')->name('get_port_description');
+        Route::patch('{portid}/description', 'LegacyApiController@update_port_description')->name('update_port_description');
     });
 
     Route::prefix('bills')->group(function () {