netboxlabs 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_<key>.<token> - 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-sdkfor Python - Use REST/GraphQL API for reading; use Diode for writing/populating
Branching (Plugin)
Requires netbox-branching plugin.
- Lifecycle: Create → Wait (PROVISIONING→READY) → Work → Sync → Merge
- Context header:
X-NetBox-Branch: {schema_id}(8-char ID, not name) - Async operations: sync/merge/revert return Job objects—poll for completion
- Dry-run: All async ops accept
{"commit": false}for validation
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-branch-api-workflow | HIGH | Complete branching lifecycle (plugin) |
| integ-branch-context-header | HIGH | Branch context with X-NetBox-Branch header (plugin) |
| integ-branch-async-operations | MEDIUM | Job polling for sync/merge/revert (plugin) |
| integ-webhook-configuration | MEDIUM | Configure webhooks |
| integ-change-tracking | LOW | Query object changes |
External References
Official Documentation
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
- NetBox Branching - Change management plugin (optional)
Community
Reference Documentation
| Document | Purpose |
|---|---|
| HUMAN.md | Human-readable guide for engineers |
| netbox-integration-guidelines.md | Comprehensive technical reference |