netbox-integration-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NetBox Integration Best Practices Skill

NetBox集成最佳实践指南

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

本指南提供了使用NetBox REST与GraphQL API构建集成和自动化的最佳实践建议。

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 API构建集成的工程师
计划使用Claude开发新自动化的团队
学习NetBox API最佳实践的开发者

范围：本指南涵盖API集成模式。不包含插件开发、自定义脚本或NetBox管理相关内容。

NetBox Version Requirements

NetBox版本要求

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.

特性	所需版本
REST API	所有版本
GraphQL API	2.9+
v2 Tokens	4.5+（推荐使用！）
v1 Token 弃用	4.7+（在此之前完成迁移）

主要目标版本：NetBox 4.4+，若需v2 token功能则需4.5+。

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

在以下场景中应用这些实践：

构建新的NetBox API集成
审查现有集成代码
排查性能问题
规划自动化架构
编写与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

等级	描述	行动
CRITICAL（严重）	存在安全漏洞、数据丢失风险、严重性能问题	必须立即修复
HIGH（高）	对性能/可靠性有显著影响	应尽快修复
MEDIUM（中）	可带来明显改进，属于最佳实践	计划解决
LOW（低）	微小改进，可选	方便时考虑处理

Quick Reference

快速参考

Authentication

身份验证

Use v2 tokens on NetBox 4.5+:
```
Bearer nbt_<key>.<token>
```
Migrate from v1 before NetBox 4.7 (deprecation planned)

NetBox 4.5+使用v2 tokens：
```
Bearer nbt_<key>.<token>
```
在NetBox 4.7前迁移v1 token（计划弃用）

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)

始终启用分页：
```
?limit=100
```
（最大1000）
使用PATCH进行部分更新，而非PUT
列表操作使用?brief=True
排除config_context：
```
?exclude=config_context
```
（对性能影响极大）
大规模场景避免使用?q=搜索过滤器；使用特定过滤器
批量操作使用列表端点和JSON数组（而非独立端点）

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

使用查询优化器：netbox-graphql-query-optimizer
所有列表查询均需分页
嵌套层级的每个列表都要分页
注意大规模场景下的偏移分页：深层偏移速度缓慢；4.5.x版本使用ID范围过滤，4.6.0+版本使用基于游标分页（#21110）
仅请求所需字段
查询深度≤3，绝不超过5

Performance

性能优化

Exclude config_context from device lists
Use brief mode for large lists
Parallelize independent requests

设备列表中排除config_context
大型列表使用精简模式（brief mode）
并行处理独立请求

Data Ingestion (Diode)

数据导入（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

高容量数据导入场景，使用Diode而非直接调用API
按名称指定依赖项，而非ID——Diode会自动解析或创建依赖
无需考虑依赖顺序——Diode会处理对象创建顺序
Python环境使用
```
pip install netboxlabs-diode-sdk
```
安装SDK
读取数据使用REST/GraphQL API；写入/填充数据使用Diode

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

需要安装netbox-branching插件。

生命周期：创建 → 等待（PROVISIONING→READY） → 工作 → 同步 → 合并
上下文头：
```
X-NetBox-Branch: {schema_id}
```
（8位ID，而非名称）
异步操作：同步/合并/回滚会返回Job对象——轮询获取完成状态
试运行：所有异步操作支持传入
```
{"commit": false}
```
进行验证

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

规则	影响等级	描述
auth-use-v2-tokens	CRITICAL	NetBox 4.5+使用v2 tokens
auth-provisioning-endpoint	MEDIUM	使用配置端点自动创建token

REST API Rules

REST API规则

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

规则	影响等级	描述
rest-list-endpoint-bulk-ops	CRITICAL	使用列表端点执行批量操作
rest-pagination-required	HIGH	列表请求必须分页
rest-patch-vs-put	HIGH	使用PATCH进行部分更新
rest-brief-mode	HIGH	列表使用?brief=True
rest-field-selection	HIGH	使用?fields=选择字段
rest-exclude-config-context	HIGH	设备列表排除config_context
rest-avoid-search-filter-at-scale	HIGH	大规模数据集避免使用q=
rest-filtering-expressions	MEDIUM	使用查找表达式
rest-custom-field-filters	MEDIUM	按自定义字段过滤
rest-nested-serializers	LOW	了解嵌套序列化器
rest-ordering-results	LOW	使用排序参数
rest-options-discovery	LOW	使用OPTIONS进行发现

GraphQL Rules

GraphQL规则

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

规则	影响等级	描述
graphql-use-query-optimizer	CRITICAL	使用查询优化器
graphql-always-paginate	CRITICAL	所有列表查询均需分页
graphql-pagination-at-each-level	HIGH	嵌套列表分页
graphql-select-only-needed	HIGH	仅请求所需字段
graphql-calibrate-optimizer	HIGH	针对生产环境校准优化器
graphql-max-depth	HIGH	查询深度≤3
graphql-prefer-filters	MEDIUM	服务端过滤
graphql-vs-rest-decision	MEDIUM	选择合适的API
graphql-complexity-budgets	LOW	设定复杂度预算

Performance Rules

性能规则

Rule	Impact	Description
perf-exclude-config-context	HIGH	Exclude config_context
perf-brief-mode-lists	HIGH	Use brief mode for lists

规则	影响等级	描述
perf-exclude-config-context	HIGH	排除config_context
perf-brief-mode-lists	HIGH	列表使用精简模式

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

规则	影响等级	描述
data-dependency-order	CRITICAL	按依赖顺序创建对象
data-site-hierarchy	MEDIUM	了解站点层级
data-ipam-hierarchy	MEDIUM	了解IPAM层级
data-custom-fields	MEDIUM	正确使用自定义字段
data-tags-usage	MEDIUM	使用标签进行分类
data-tenant-isolation	MEDIUM	使用租户进行隔离
data-natural-keys	MEDIUM	使用自然键

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

规则	影响等级	描述
integ-diode-ingestion	HIGH	高容量数据导入使用Diode
integ-pynetbox-client	HIGH	Python环境使用pynetbox
integ-branch-api-workflow	HIGH	完整执行分支生命周期（插件）
integ-branch-context-header	HIGH	使用X-NetBox-Branch头指定分支上下文（插件）
integ-branch-async-operations	MEDIUM	同步/合并/回滚操作轮询Job状态（插件）
integ-webhook-configuration	MEDIUM	配置webhook
integ-change-tracking	LOW	查询对象变更

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)

pynetbox - 官方Python客户端
netbox-graphql-query-optimizer - 查询分析工具（GraphQL必备）
Diode - 数据导入服务（高容量写入场景）
Diode Python SDK - Diode的Python客户端
NetBox Branching - 变更管理插件（可选）

Community

社区资源

Reference Documentation

参考文档

Document	Purpose
HUMAN.md	Human-readable guide for engineers
netbox-integration-guidelines.md	Comprehensive technical reference

文档	用途
HUMAN.md	面向工程师的可读指南
netbox-integration-guidelines.md	综合技术参考