mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
65b40bc870
Nothing major, just spotted it as I went through the docs. DO NOT DELETE THIS TEXT #### Please note > Please read this information carefully. You can run `./scripts/pre-commit.php` to check your code before submitting. - [x] Have you followed our [code guidelines?](http://docs.librenms.org/Developing/Code-Guidelines/) #### Testers If you would like to test this pull request then please run: `./scripts/github-apply <pr_id>`, i.e `./scripts/github-apply 5926`
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
source: API/index.md
|
|
|
|
## Versioning
|
|
|
|
Versioning an API is a minefield which saw us looking at numerous options on how to do this. Paul wrote an excellent blog post which touches on this: <https://blog.librenms.org/2014/09/restful-apis/>
|
|
|
|
We have currently settled on using versioning within the API end point itself `/api/v0`. As the API itself is new and still in active development we also decided that v0 would be the best starting point to indicate it's in development.
|
|
|
|
## Tokens
|
|
|
|
To access any of the token end points you will be required to authenticate using a token. Tokens can be created directly from within the LibreNMS web interface by going to `/api-access/`.
|
|
|
|
- Click on 'Create API access token'.
|
|
- Select the user you would like to generate the token for.
|
|
- Enter an optional description.
|
|
- Click Create API Token.
|
|
|
|
## Endpoints
|
|
|
|
Whilst this documentation will describe and show examples of the end points, we've designed the API so you should be able to traverse through it without knowing any of the available API routes.
|
|
|
|
You can do this by first calling `/api/v0`:
|
|
|
|
```curl
|
|
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0
|
|
```
|
|
|
|
Output:
|
|
```json
|
|
{
|
|
"list_bgp": "https://librenms.org/api/v0/bgp",
|
|
...
|
|
"edit_rule": "https://librenms.org/api/v0/rules"
|
|
}
|
|
```
|
|
|
|
## Input
|
|
|
|
Input to the API is done in three different ways, sometimes a combination two or three of these.
|
|
|
|
- Passing parameters via the api route. For example when obtaining a devices details you will pass the hostname of the device in the route: `/api/v0/devices/:hostname`.
|
|
- Passing parameters via the query string. For example you can list all devices on your install but limit the output to devices that are currently down: `/api/v0/devices?type=down`
|
|
- Passing data in via JSON, this will mainly be used when adding or updating information via the API, for instance adding a new device:
|
|
```curl
|
|
curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}'-H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/devices
|
|
```
|
|
|
|
## Output
|
|
|
|
Output from the API currently is via two output types:
|
|
|
|
- JSON Most API responses will output json. As show in the example for calling the API endpoint.
|
|
- PNG This is for when the request is for an image such as a graph for a switch port.
|
|
|
|
## Endpoint Categories
|
|
|
|
- [Devices](Devices.md)
|
|
- [DeviceGroups](DeviceGroups.md)
|
|
- [Ports](Ports.md)
|
|
- [PortGroups](PortGroups.md)
|
|
- [Alerts](Alerts.md)
|
|
- [Routing](Routing.md)
|
|
- [Switching](Switching.md)
|
|
- [Inventory](Inventory.md)
|
|
- [Bills](Bills.md)
|
|
- [ARP](ARP.md)
|
|
- [Services](Services.md)
|
|
- [Logs](Logs.md)
|
|
- [System](System.md)
|