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
2.6 KiB
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 -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0
Output:
{
"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 -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.