mirror of
https://github.com/librenms/librenms.git
synced 2024-10-07 16:52:45 +00:00
6575042f5f
* clean up all but header incrementing in Creating-Transport.md * make Device-Dependencies.md mdl happy * make Entities.md as mdl happy as possible... one long table line left * make mdl as happy as possible for index.md * clean up Introduction.md as much as possible * minor formatting cleanup... move each icon onto its own row * make ack and notes the same style * clean Macros.md up * clean Rules.md up as much as possible * tweak one line a bit to get it to format a bit nicer * a bit more format tweaking, making sure it does not sure with > * clean up as much as possible for Templates.md * make Testing.md as mdl happy as possibly * clean Transports.md up as much as possible * clean as many issues as possible for Alerts.md * clean up as much of ARP.md as possible * clean up as much as possible for Bills.md * make DeviceGroups.md as mdl happy as possible * cleanup Devices.md * make as mdl happy as possible Inventory.md and index.md * mdl cleanup for Logs.md and PortGroups.md * make Ports.md and Routing.md as happy as possible * clean up Services.md, Switching.md, and Systems.md as much as possible * more markup cleanup * lots more md cleanup udner Devloping/ * reapply bits from #10343 that accidentally got removed when merging
88 lines
2.6 KiB
Markdown
88 lines
2.6 KiB
Markdown
source: API/index.md
|
|
path: blob/master/doc/
|
|
|
|
## 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)
|