Add get_ports_by_group API function (#13361)

* implement api route get_ports_by_group

* Update API docs for new get_ports_by_group

* Fix misspelling of function names and routes

doc/API/Port_Groups.md

@@ -1,20 +1,16 @@
 source: API/Port_Groups.md
 path: blob/master/doc/
 
-### `get_portgroups`
+### `get_port_groups`
 
 List all port groups.
 
-Route: `/api/v0/portgroups`
-
-Input (JSON):
-
-  -
+Route: `/api/v0/port_groups`
 
 Examples:
 
 ```curl
-curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/portgroups
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/port_groups
 ```
 
 Output:
@@ -36,7 +32,45 @@ Output:
 ]
 ```
 
-### `add_portgroup`
+### `get_ports_by_group`
+
+List all ports matching the group provided.
+
+Route: `/api/v0/port_groups/:name`
+
+- name Is the name of the port group which can be obtained using
+  [`get_port_groups`](#function-get_port_groups). Please ensure that
+  the name is urlencoded if it needs to be (i.e Linux Servers would
+  need to be urlencoded.
+
+Params:
+
+- full: set to any value to return all data for the devices in a given group
+
+Examples:
+
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/port_groups/Billable
+```
+
+Output:
+
+```json
+{
+    "status": "ok",
+    "ports": [
+        {
+            "port_id": 1376
+        },
+        {
+            "port_id": 2376
+        }
+    ],
+    "count": 2
+}
+```
+
+### `add_port_group`
 
 Add a new port group. Upon success, the ID of the new port group is returned
 and the HTTP response code is `201`.
@@ -70,7 +104,7 @@ Output:
 }
 ```
 
-### `assign_portgroup`
+### `assign_port_group`
 
 Assign a Port Group to a list of Ports
 
@@ -97,7 +131,7 @@ Output:
 }
 ```
 
-### `remove_portgroup`
+### `remove_port_group`
 
 Remove a Port Group from a list of Ports
 

includes/html/api_functions.inc.php

@@ -1977,6 +1977,28 @@ function get_port_groups(Illuminate\Http\Request $request)
     return api_success($groups->makeHidden('pivot')->toArray(), 'groups', 'Found ' . $groups->count() . ' port groups');
 }
 
+function get_ports_by_group(Illuminate\Http\Request $request)
+{
+    $name = $request->route('name');
+    if (! $name) {
+        return api_error(400, 'No port group name provided');
+    }
+
+    $port_group = ctype_digit($name) ? PortGroup::find($name) : PortGroup::where('name', $name)->first();
+
+    if (empty($port_group)) {
+        return api_error(404, 'Port group not found');
+    }
+
+    $ports = $port_group->ports()->get($request->get('full') ? ['*'] : ['ports.port_id']);
+
+    if ($ports->isEmpty()) {
+        return api_error(404, 'No ports found in group ' . $name);
+    }
+
+    return api_success($ports->makeHidden('pivot')->toArray(), 'ports');
+}
+
 function assign_port_group(Illuminate\Http\Request $request)
 {
     $port_group_id = $request->route('port_group_id');

routes/api.php

@@ -25,6 +25,7 @@ Route::group(['prefix' => 'v0', 'namespace' => '\App\Api\Controllers'], function
         Route::get('devicegroups/{name}', 'LegacyApiController@get_devices_by_group')->name('get_devices_by_group');
         Route::get('devicegroups', 'LegacyApiController@get_device_groups')->name('get_device_groups');
         Route::get('port_groups', 'LegacyApiController@get_port_groups')->name('get_port_groups');
+        Route::get('port_groups/{name}', 'LegacyApiController@get_ports_by_group')->name('get_ports_by_group');
         Route::get('portgroups/multiport/bits/{id}', 'LegacyApiController@get_graph_by_portgroup')->name('get_graph_by_portgroup_multiport_bits');
         Route::get('portgroups/{group}', 'LegacyApiController@get_graph_by_portgroup')->name('get_graph_by_portgroup');
         Route::get('alerts/{id}', 'LegacyApiController@list_alerts')->name('get_alert');