netbox-integration-best-practices

NetBox Integration Best Practices Skill

This skill provides best practices guidance for building integrations and automations with NetBox REST and GraphQL APIs.

Target Audience Engineers building integrations atop NetBox APIs Teams planning new automations with Claude Developers learning NetBox API best practices

Scope: This skill covers API integration patterns. It does NOT cover plugin development, custom scripts, or NetBox administration.

NetBox Version Requirements Feature Version Required REST API All versions GraphQL API 2.9+ v2 Tokens 4.5+ (use these!) v1 Token Deprecation 4.7+ (migrate before this)

Primary target: NetBox 4.4+ with 4.5+ for v2 token features.

When to Apply This Skill

Apply these practices when:

Building new NetBox API integrations Reviewing existing integration code Troubleshooting performance issues Planning automation architecture Writing scripts that interact with NetBox Priority Levels Level Description Action CRITICAL Security vulnerabilities, data loss, severe performance Must fix immediately HIGH Significant performance/reliability impact Should fix soon MEDIUM Notable improvements, best practices Plan to address LOW Minor improvements, optional Consider when convenient Quick Reference Authentication Use v2 tokens on NetBox 4.5+: Bearer nbt_. Migrate from v1 before NetBox 4.7 (deprecation planned) REST API Always paginate: ?limit=100 (max 1000) Use PATCH for partial updates, not PUT Use ?brief=True for list operations Exclude config_context: ?exclude=config_context (major performance impact) Avoid ?q= search filter at scale; use specific filters Bulk operations use list endpoints with JSON arrays (not separate endpoints) GraphQL Use the query optimizer: netbox-graphql-query-optimizer Always paginate every list query Paginate at every level of nesting Beware offset pagination at scale: Deep offsets are slow; use ID range filtering in 4.5.x, cursor-based in 4.6.0+ (#21110) Request only needed fields Keep depth ≤3, never exceed 5 Performance Exclude config_context from device lists Use brief mode for large lists Parallelize independent requests Data Ingestion (Diode) For high-volume data ingestion, use Diode instead of direct API Specify dependencies by name, not ID—Diode resolves or creates them No dependency order needed—Diode handles object creation order Use pip install netboxlabs-diode-sdk for Python Use REST/GraphQL API for reading; use Diode for writing/populating Rules by Category Authentication Rules Rule Impact Description auth-use-v2-tokens CRITICAL Use v2 tokens on NetBox 4.5+ auth-provisioning-endpoint MEDIUM Use provisioning endpoint for automated token creation REST API Rules Rule Impact Description rest-list-endpoint-bulk-ops CRITICAL Use list endpoints for bulk operations rest-pagination-required HIGH Always paginate list requests rest-patch-vs-put HIGH Use PATCH for partial updates rest-brief-mode HIGH Use ?brief=True for lists rest-field-selection HIGH Use ?fields= to select fields rest-exclude-config-context HIGH Exclude config_context from device lists rest-avoid-search-filter-at-scale HIGH Avoid q= with large datasets rest-filtering-expressions MEDIUM Use lookup expressions rest-custom-field-filters MEDIUM Filter by custom fields rest-nested-serializers LOW Understand nested serializers rest-ordering-results LOW Use ordering parameter rest-options-discovery LOW Use OPTIONS for discovery GraphQL Rules Rule Impact Description graphql-use-query-optimizer CRITICAL Use query optimizer graphql-always-paginate CRITICAL Paginate every list query graphql-pagination-at-each-level HIGH Paginate nested lists graphql-select-only-needed HIGH Request only needed fields graphql-calibrate-optimizer HIGH Calibrate against production graphql-max-depth HIGH Keep depth ≤3 graphql-prefer-filters MEDIUM Filter server-side graphql-vs-rest-decision MEDIUM Choose appropriate API graphql-complexity-budgets LOW Establish complexity budgets Performance Rules Rule Impact Description perf-exclude-config-context HIGH Exclude config_context perf-brief-mode-lists HIGH Use brief mode for lists Data Modeling Rules Rule Impact Description data-dependency-order CRITICAL Create objects in dependency order data-site-hierarchy MEDIUM Understand site hierarchy data-ipam-hierarchy MEDIUM Understand IPAM hierarchy data-custom-fields MEDIUM Use custom fields properly data-tags-usage MEDIUM Use tags for classification data-tenant-isolation MEDIUM Use tenants for separation data-natural-keys MEDIUM Use natural keys Integration Rules Rule Impact Description integ-diode-ingestion HIGH Use Diode for high-volume data ingestion integ-pynetbox-client HIGH Use pynetbox for Python integ-webhook-configuration MEDIUM Configure webhooks integ-change-tracking LOW Query object changes External References Official Documentation NetBox Documentation REST API Guide GraphQL API Guide Essential Tools pynetbox - Official Python client netbox-graphql-query-optimizer - Query analysis (essential for GraphQL) Diode - Data ingestion service (for high-volume writes) Diode Python SDK - Python client for Diode Community NetBox GitHub NetBox Discussions Reference Documentation Document Purpose HUMAN.md Human-readable guide for engineers netbox-integration-guidelines.md Comprehensive technical reference