API¶
pynautobot.core.api
¶
API module for pynautobot.
pynautobot.core.api.Api
¶
The Api object is the primary entry point for interacting with a Nautobot instance using pynautobot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url |
str
|
The base URL of the Nautobot instance you want to connect to. |
required |
token |
str
|
Your Nautobot authentication token. |
None
|
threading |
bool
|
Enable threading for |
False
|
max_workers |
int
|
The maximum number of worker threads to use
for |
4
|
api_version |
str
|
Override the default Nautobot REST API version used for all requests. |
None
|
retries |
int
|
The number of retries for HTTP status codes
429, 500, 502, 503, and 504. Defaults to 0 (no retries). When the server
sends a |
0
|
verify |
bool
|
Whether to verify SSL certificates. Defaults to |
True
|
exclude_m2m |
bool
|
(Nautobot 2.4+) Whether to exclude/include
many-to-many relationships for get/filter/all requests. Defaults to |
None
|
include_default |
str
|
A comma-separated list of items to include
by default for get/filter/all requests. Defaults to |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
circuits |
An instance of the |
|
cloud |
An instance of the |
|
core |
An instance of the |
|
data_validation |
An instance of the |
|
dcim |
An instance of the |
|
extras |
An instance of the |
|
ipam |
An instance of the |
|
load_balancers |
An instance of the |
|
tenancy |
An instance of the |
|
ui |
An instance of the |
|
users |
An instance of the |
|
virtualization |
An instance of the |
|
vpn |
An instance of the |
|
wireless |
An instance of the |
|
http_session |
Session
|
The underlying HTTP session object used for making requests to Nautobot. You can override the default session with your own to control HTTP behavior such as SSL verification, custom headers, retries, and timeouts. See the documentation on custom sessions for more information. |
rate_limit |
RateLimit | None
|
Rate limit information from the most recent response that reported it (Nautobot 3.3+ with rate limiting enabled). |
Raises:
| Type | Description |
|---|---|
AttributeError
|
If an invalid application name is provided. |
Examples:
>>> import pynautobot
>>> nb = pynautobot.api(
... 'http://localhost:8000',
... token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> nb.dcim.devices.all()
rate_limit
property
¶
Rate limit information from the most recent response that reported it.
Requires Nautobot 3.3+ with rate limiting set to report or enforce mode.
With threading=True, this reflects whichever response arrived last. If you replace
http_session with your own session, this is no longer updated; use
RequestError.rate_limit on failed requests instead.
Returns:
| Type | Description |
|---|---|
RateLimit | None
|
The latest rate limit information, or |
Examples:
version
property
¶
Retrieves the version of the Nautobot REST API that the connected instance is using.
This method can be helpful for checking API compatibility and determining if specific features or syntaxes are available.
Returns:
| Type | Description |
|---|---|
str
|
The Nautobot API version string. |
Raises:
| Type | Description |
|---|---|
RequestException
|
If there is an error fetching the version information from Nautobot. |
Examples:
__init__(url, token=None, threading=False, max_workers=4, api_version=None, retries=0, verify=True, exclude_m2m=None, include_default=None)
¶
Initialize the Api object.
openapi()
¶
Retrieves the OpenAPI specification (OAS) document for the connected Nautobot instance.
The OpenAPI specification provides a machine-readable description of the Nautobot REST API, including available endpoints, parameters, request and response formats, and more.
This can be useful for tools like code generation or API clients in other languages.
Returns:
| Type | Description |
|---|---|
dict
|
The OpenAPI specification document as a Python dictionary. |
Raises:
| Type | Description |
|---|---|
RequestException
|
If there is an error fetching the OpenAPI spec from Nautobot. |
Examples:
status()
¶
Retrieves status information about the connected Nautobot instance.
This method provides various details about the Nautobot instance, including:
- Django version
- Installed apps and their versions
- Nautobot version
- Active plugins (if any)
- Python version
- Number of running RQ workers (if applicable)
Availability: Requires Nautobot version 2.10.0 or newer.
Returns:
| Type | Description |
|---|---|
dict
|
A dictionary containing the status information as returned by Nautobot. |
Raises:
| Type | Description |
|---|---|
RequestError
|
If the request to Nautobot fails. |
Examples:
>>> import pprint
>>> nb = pynautobot.api(
... 'http://localhost:8000',
... token='d6f4e314a5b5fefd164995169f28ae32d987704f'
... )
>>> pprint.pprint(nb.status())
{'django-version': '3.1.3',
'installed-apps': {...},
'nautobot-version': '1.0.0',
'plugins': {},
'python-version': '3.7.3',
'rq-workers-running': 1}