Crate netbox

Source

Expand description

§client library

this crate provides a typed, ergonomic client for the netbox 4.x rest api.

§features

typed resources - strongly-typed request/response models for all netbox endpoints
crud operations - list, get, create, update, patch, delete with query filtering
pagination - iterator-based pagination with automatic page fetching
bulk operations - batch create, update, patch, and delete
specialized endpoints - ipam availability, dcim cable tracing, config rendering, task management
graphql - read-only graphql query support
error handling - structured errors with status codes and api messages

§modules

the client exposes netbox endpoints through typed module accessors:

client.dcim() - devices, interfaces, sites, racks, cables, power
client.ipam() - prefixes, ip addresses, vlans, vrfs, asns
client.circuits() - providers, circuits, terminations
client.virtualization() - clusters, virtual machines, vm interfaces
client.tenancy() - tenants, contacts
client.extras() - tags, custom fields, config contexts, webhooks
client.core() - background tasks, data sources, jobs
client.users() - users, groups, tokens, permissions
client.vpn() - tunnels, ike/ipsec policies, l2vpns
client.wireless() - wireless lans, links
client.plugins() - netbox-branching plugin support

each module returns typed Resource<T> handles with standard crud methods, plus specialized action methods where applicable.

§resource pattern

all netbox endpoints follow the same pattern. access a module, then a resource, then call an action:

client.{module}().{resource}().{action}()

every Resource<T> provides these standard methods:

method	http	description
`list(query)`	GET	fetch paginated results with optional filters
`get(id)`	GET	fetch a single item by id
`create(body)`	POST	create a new item
`update(id, body)`	PUT	full replacement update
`patch(id, body)`	PATCH	partial update
`delete(id)`	DELETE	remove an item
`bulk_create(items)`	POST	create multiple items
`bulk_update(items)`	PUT	full update multiple items
`bulk_patch(items)`	PATCH	partial update multiple items
`bulk_delete(items)`	DELETE	remove multiple items
`paginate(query)`	GET	returns an iterator for all pages

§query filtering

use QueryBuilder to filter, sort, and limit results:

QueryBuilder::new()
    .filter("key", "value")     // add a filter
    .filter("status", "active") // filters are additive
    .search("term")             // full-text search
    .order_by("name")           // sort ascending
    .order_by("-created")       // sort descending (prefix with -)
    .limit(50)                  // max results per page
    .offset(100)                // skip first N results

pass the builder to list() or paginate() to apply filters.

§install

[dependencies]
netbox = "0.3"
tokio = { version = "1.0", features = ["full"] }

§create a client

use netbox::{Client, ClientConfig};

fn example() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig::new("https://netbox.example.com", "token");
    let _client = Client::new(config)?;
    Ok(())
}

§auth and config

use std::time::Duration;
use netbox::ClientConfig;
use reqwest::header::{HeaderName, HeaderValue};

fn example() {
    let _config = ClientConfig::new("https://netbox.example.com", "token")
        .with_timeout(Duration::from_secs(60))
        .with_max_retries(5)
        .with_ssl_verification(false)
        .with_header(
            HeaderName::from_static("x-netbox-client"),
            HeaderValue::from_static("custom"),
        );
}

§http client access

use netbox::{Client, ClientConfig};

fn example() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
    let http = client.http_client();
    let _ = http;
    Ok(())
}

§list and filter

use netbox::{Client, ClientConfig, QueryBuilder};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let query = QueryBuilder::new()
    .filter("status", "active")
    .limit(50)
    .order_by("name");

let page = client.dcim().devices().list(Some(query)).await?;
println!("{}", page.count);

§paginate

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let mut paginator = client.dcim().devices().paginate(None)?;
while let Some(page) = paginator.next_page().await? {
    for device in page.results {
        let display = device.display.as_deref().unwrap_or("<unknown>");
        println!("{display}");
    }
}

note: for local dev instances with self-signed certs, call with_ssl_verification(false) in your config. note: paginate returns Result<Paginator<T>>. handle errors before calling next_page.

§dynamic resources

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let resource = client.resource("ipam/vrfs/");
let page = resource.list(None).await?;
println!("{}", page.count);

§create, update, delete

use netbox::{Client, ClientConfig};
use netbox::dcim::CreateDeviceRequest;

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let request = CreateDeviceRequest {
    name: "switch-01".to_string(),
    device_type: 1,
    role: 1,
    site: 1,
    status: Some("active".to_string()),
    serial: None,
    asset_tag: None,
    tags: None,
};

let device = client.dcim().devices().create(&request).await?;
let device_id = device.id.expect("device id missing from response") as u64;
let _updated = client
    .dcim()
    .devices()
    .patch(device_id, &serde_json::json!({"status": "offline"}))
    .await?;
client.dcim().devices().delete(device_id).await?;

§bulk operations

use netbox::{BulkDelete, BulkUpdate, Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;

let updates = vec![
    BulkUpdate::new(1, serde_json::json!({"status": "offline"})),
    BulkUpdate::new(2, serde_json::json!({"status": "offline"})),
];
let _updated = client.dcim().devices().bulk_patch(&updates).await?;

let deletes = vec![BulkDelete::new(1), BulkDelete::new(2)];
client.dcim().devices().bulk_delete(&deletes).await?;

§status and schema

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let status = client.status().status().await?;
let schema = client.schema().schema(Some("json"), None).await?;

§graphql (read-only)

returns the data field when present.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let data = client
    .graphql()
    .query("{ devices { name } }", None)
    .await?;
println!("{}", data);

§connected device

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let devices = client
    .dcim()
    .connected_device("leaf-01", "Ethernet1")
    .await?;
println!("{}", devices.len());

§branching plugin

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let branches = client.plugins().branches().list(None).await?;
println!("{}", branches.count);

§ipam availability

query and allocate available IPs, prefixes, VLANs, and ASNs.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;

// list available IPs in a prefix
let available = client.ipam().available_ips_in_prefix(1).await?;
println!("{} IPs available", available.len());

// allocate IPs from a prefix
let requests = vec![serde_json::json!({"description": "allocated via api"})];
let created = client.ipam().create_available_ips_in_prefix(1, &requests).await?;
println!("created {} IPs", created.len());

// list available VLANs in a group
let vlans = client.ipam().available_vlans_in_group(1).await?;
println!("{} VLANs available", vlans.len());

§dcim trace

trace cable paths for interfaces and power components.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let trace = client.dcim().trace_interface(42).await?;
println!("{:?}", trace);

§core task management

manage background tasks and sync data sources.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;

// sync a data source
let source = client.core().sync_data_source(1).await?;
println!("{:?}", source);

// manage background tasks
let task = client.core().enqueue_task("abc123").await?;
println!("{:?}", task);

§extras sync and render

sync config contexts/templates from data sources and render templates.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;

// sync a config context from its data source
let context = client.extras().sync_config_context(1).await?;
println!("{:?}", context);

// render a config template
let output = client.extras().render_config_template(1).await?;
println!("{}", output);

§virtualization render config

render configuration for virtual machines.

use netbox::{Client, ClientConfig};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let config = client.virtualization().render_vm_config(1).await?;
println!("{}", config);

§error handling

use netbox::{Client, ClientConfig, Error};

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
match client.dcim().devices().get(999u64).await {
    Ok(device) => println!("{}", device.display.as_deref().unwrap_or("<unknown>")),
    Err(Error::ApiError { status, .. }) if status == 404 => {
        println!("not found");
    }
    Err(e) if e.is_auth_error() => {
        println!("auth failed: {}", e);
    }
    Err(e) => {
        println!("error: {}", e);
    }
}

§raw api access

use this when you need an endpoint not yet wrapped by the high-level client.

use netbox::{Client, ClientConfig};
use netbox::openapi::apis::dcim_api;

let client = Client::new(ClientConfig::new("https://netbox.example.com", "token"))?;
let openapi_config = client.openapi_config()?;
let device = dcim_api::dcim_devices_retrieve(&openapi_config, 42).await?;
println!("{}", device.display.as_deref().unwrap_or("<unknown>"));

§coverage summary

high-level resource coverage exists for dcim, circuits, core, extras, ipam, tenancy, users, virtualization, vpn, and wireless. additional endpoints include status, schema, connected-device, graphql (read-only), and netbox-branching plugin resources.

action endpoints include ipam availability queries (prefixes, ip-ranges, vlan-groups, asn-ranges), dcim cable tracing, core task management and data source sync, extras config sync/render operations, and virtualization vm config rendering.

Modules§

circuits: circuits and provider resources. circuits endpoints for providers, circuits, terminations, and virtual circuits.
core: core endpoints and system resources. core endpoints for background tasks, data sources, and system metadata.
dcim: dcim endpoints. dcim endpoints for devices, racks, sites, interfaces, and inventory.
extras: extras endpoints (tags, webhooks, scripts, custom fields). extras endpoints for tags, webhooks, scripts, and custom fields.
graphql: graphql query helper. graphql endpoint helper.
ipam: ipam endpoints. ipam endpoints for prefixes, addresses, vrfs, vlans, and asns.
models
openapi: generated openapi types and api functions.
plugins: plugin endpoints. plugin endpoints, including netbox-branching resources.
schema: schema endpoint. schema endpoint for fetching the openapi document.
status: status endpoint. status endpoint for basic health and version info.
tenancy: tenancy endpoints. tenancy endpoints for tenants, groups, and contacts.
users: users and auth endpoints. users, groups, tokens, and permissions.
virtualization: virtualization endpoints. virtualization endpoints for clusters, vms, and interfaces.
vpn: vpn endpoints. vpn endpoints for tunnels, l2vpns, and ipsec resources.
wireless: wireless endpoints. wireless endpoints for lans, groups, and links.

Structs§

BulkDelete: bulk delete wrapper that includes the id to delete.
BulkUpdate: bulk update wrapper that includes an id with the update payload.
Client: the main netbox api client
ClientConfig: configuration for the netbox client
Page: a paginated response from the netbox api
Paginator: iterator for paginated api results
QueryBuilder: builder for constructing query parameters for netbox api requests
Resource: generic resource wrapper for list/get/create/update/patch/delete operations.

Enums§

Error: main error type for netbox operations

Type Aliases§

Result: result type alias using our Error type

Crate netbox

Crate netbox Copy item path

§client library

§features

§modules

§resource pattern

§query filtering

§install

§create a client

§auth and config

§http client access

§list and filter

§paginate

§dynamic resources

§create, update, delete

§bulk operations

§status and schema

§graphql (read-only)

§connected device

§branching plugin

§ipam availability

§dcim trace

§core task management

§extras sync and render

§virtualization render config

§error handling

§raw api access

§coverage summary

Modules§

Structs§

Enums§

Type Aliases§

Crate netbox