Skip to content
Python client API for Netbox
Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
netboxapi Fix mappers comparaison Feb 12, 2019
tests Fix mappers comparaison Feb 12, 2019
.gitignore Initial commit Mar 27, 2017
.travis.yml Add python 3.7 in travis and tox Jul 5, 2018
LICENSE.md Initial commit Mar 27, 2017
MANIFEST.in Initial commit Mar 27, 2017
README.md Fix travis status url Jun 22, 2019
setup.cfg Bump version: 1.1.6 → 1.1.7 Feb 12, 2019
setup.py Bump version: 1.1.6 → 1.1.7 Feb 12, 2019
tox.ini Add python 3.7 in travis and tox Jul 5, 2018

README.md

Python Netbox API

Build Status Coverage Status

Python client API for Netbox, using requests.

Usage

Netbox API

Import NetboxAPI:

from netboxapi import NetboxAPI

Initialize a new NetboxAPI object:

netbox_api = NetboxAPI(url="netbox.example.com/api")

# or if you enabled the authentication
netbox_api = NetboxAPI(
    url="netbox.example.com/api", username="user", password="password"
)

# or if you have generated a token
netbox_api = NetboxAPI(
    url="netbox.example.com/api", token="token"
)

# but the following is useless, as the token will not be used
netbox_api = NetboxAPI(
    url="netbox.example.com/api", username="user", password="password",
    token="token"
)

Then use multiple available methods to interact with the api:

>>> netbox_api.get("dcim/sites/1/racks/")
{
    "id": 1,
    "name": "Some rack",
    …
}

>>> netbox_api.post("dcim/device-roles/", json={"name": "test", …},)
{
    "id": 1,
    "name": "test",
    …
}

>>> netbox_api.patch("dcim/device-roles/", json={"slug": "test"},)
{
    "id": 1,
    "name": "test",
    "slug": "test",
    …
}

>>> netbox_api.put("dcim/device-roles/1/", json={"name": "test", …},)
{
    "id": 1,
    "name": "test",
    "slug": "test",
    …
}

>>> netbox_api.delete("dcim/sites/1/")
<<Response [204]>>

Netbox Mapper

NetboxMapper is available to interact with Netbox objects. Received json from the netbox API is converted into mapper objects, by setting its attributes accordingly to the dict. To use it, first import NetboxMapper:

from netboxapi import NetboxAPI, NetboxMapper

Initialize a new NetboxMapper object:

netbox_api = NetboxAPI(
    url="netbox.example.com/api", username="user", password="password"
)
netbox_mapper = NetboxMapper(netbox_api, app_name="dcim", model="sites")

GET

Then get all objects of the model:

>>> sites = list(netbox_mapper.get())
[<NetboxMapper>, <NetboxMapper>, …]

>>> print(sites[0].id)
1
>>> print(sites[0].name)
"Some site"

Or get a specific site by its id:

>>> netbox_mapper.get(1)

It is possible to get a subresourses of an object, and/or specify a query:

>>> netbox_mapper.get("1", "racks", q="name_to_filter")

Any kwargs (here q=) is used as a GET parameter for the request.

Pagination is transparently handled, but it is possible to specify how many items are wanted per page by setting the GET parameter limit, to limit the number of requests done to Netbox in case of long iterations.

Foreign keys

Foreign keys are handle automatically by the mapper.

>>> site = next(netbox_mapper.get())
>>> print(site.region.name)
"Some region"

When accessing to site.region, a query will be done to fetch the foreign object. It will then be saved in cache to avoid unnecessary queries for next accesses.

To refresh an object and its foreign keys, just do:

>>> site = next(site.get())

POST

Use the kwargs of a mapper to send a post request and create a new object:

>>> netbox_mapper.post(name="A site", slug="a_site", region="Some region")
<NetboxMapper>  # corresponding to the new created object

If a mapper is sent as parameter, post() will automatically take its id. However, it will not update the foreign object.

PUT

Use put() in a child mapper to update the resource upstream by reflecting the changes made in the object attributes:

>>> child_mapper = netbox_mapper.get(1)
>>> child_mapper.name = "another name"
>>> child_mapper.put()
<requests>  # requests object containing the netbox response

PATCH

PATCH is not supported in mappers, as it does not make really sense (to me) with the mapper logic.

DELETE

Delete an object upstream by calling delete():

>>> netbox_mapper.delete(1)
<requests>  # requests object containing the netbox response

# OR

>>> child_mapper = netbox_mapper.get(1)
>>> child_mapper.delete()
<requests>  # requests object containing the netbox response

But trying to delete another object of the same model from a child mapper is not possible:

>>> child_mapper = netbox_mapper.get(1)
>>> child_mapper.delete(2)
Exception ForbiddenAsChildError

Dependencies

  • python 3.4 (it certainly works with prior versions, just not tested)

License

Tool under the BSD license. Do not hesitate to report bugs, ask me some questions or do some pull request if you want to!

You can’t perform that action at this time.