mirror/librenms-librenms
1
0
Fork 0
mirror of https://github.com/librenms/librenms.git synced 2024-10-07 16:52:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Standardize device and device group maintenance API (#14153)

Browse Source 
* Standardise device and devicegroup maintenance API

* styleci fixes
This commit is contained in:
rhinoau
2022-07-29 00:38:46 +08:00
committed by GitHub
parent 91e7b062c5
commit d248e6561f
3 changed files with 116 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/API/DeviceGroups.md
View File

@@ -150,15 +150,28 @@ Route: `/api/v0/devicesgroups/:name/maintenance`
Input (JSON):
- title: Some title for the Maintenance
- notes: Some description for the Maintenance
- start: Start time of Maintenance in format H:m
- duration: Duration of Maintenance in format H:m
- `title`: *optional* - Some title for the Maintenance
Will be replaced with device group name if omitted
- `notes`: *optional* - Some description for the Maintenance
- `start`: *optional* - start time of Maintenance in full format `Y-m-d H:i:00`
eg: 2022-08-01 22:45:00
Current system time `now()` will be used if omitted
- `duration`: *required* - Duration of Maintenance in format `H:i` / `Hrs:Mins`
eg: 02:00
Example:
Example with start time:
```curl
curl -X POST -d '{"title":"Device group Maintenance","notes":"A 2 hour Maintenance triggered via API","start":"04:30","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
--data-raw '
{
"title":"Device group Maintenance",
"notes":"A 2 hour Maintenance triggered via API with start time",
"start":"2022-08-01 08:00:00",
"duration":"2:00"
}
'
```
Output:
@@ -166,6 +179,30 @@ Output:
```json
{
"status": "ok",
"message": "Device group Cisco switches (2) will begin maintenance mode at 5:00 for 2:00 h"
"message": "Device group Cisco switches (2) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}
```
Example with no start time:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devicegroups/Cisco%20switches/maintenance/ \
--data-raw '
{
"title":"Device group Maintenance",
"notes":"A 2 hour Maintenance triggered via API with no start time",
"duration":"2:00"
}
'
```
Output:
```json
{
"status": "ok",
"message": "Device group Cisco switches (2) moved into maintenance mode for 2:00h"
}
```

48
doc/API/Devices.md
View File

@@ -1109,13 +1109,28 @@ Route: `/api/v0/devices/:hostname/maintenance`
Input (JSON):
- notes: Some description for the Maintenance
- duration: Duration of Maintenance in format H:m
- `title`: *optional* - Some title for the Maintenance
Will be replaced with hostname if omitted
- `notes`: *optional* - Some description for the Maintenance
Will also be added to device notes if user prefs "Add schedule notes to devices notes" is set
- `start`: *optional* - start time of Maintenance in full format `Y-m-d H:i:00`
eg: 2022-08-01 22:45:00
Current system time `now()` will be used if omitted
- `duration`: *required* - Duration of Maintenance in format `H:i` / `Hrs:Mins`
eg: 02:00
Example:
Example with start time:
```curl
curl -X POST -d '{"notes":"A 2 hour Maintenance triggered via API","duration":"2:00"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/localhost/maintenance
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
--data-raw '
"title":"Device Maintenance",
"notes":"A 2 hour Maintenance triggered via API with start time",
"start":"2022-08-01 08:00:00",
"duration":"2:00"
}
'
```
Output:
@@ -1123,10 +1138,33 @@ Output:
```json
{
"status": "ok",
"message": "Device localhost.localdomain (57) moved into maintenance mode for 2:00 h"
"message": "Device localhost (1) will begin maintenance mode at 2022-08-01 22:45:00 for 2:00h"
}
```
Example with no start time:
```curl
curl -H 'X-Auth-Token: YOURAPITOKENHERE' \
-X POST https://librenms.org/api/v0/devices/localhost/maintenance/ \
--data-raw '
"title":"Device Maintenance",
"notes":"A 2 hour Maintenance triggered via API with no start time",
"duration":"2:00"
}
'
```
Output:
```json
{
"status": "ok",
"message": "Device localhost (1) moved into maintenance mode for 2:00h"
}
```
### `add_device`
Add a new device. Most fields are optional. You may omit snmp