用途：为基于 NetBox REST 与 GraphQL API 构建集成与自动化的工程师提供最佳实践指导，适用于新建集成、审查现有集成代码、排查性能问题、规划自动化架构以及编写与 NetBox 交互的脚本。范围仅限 API 集成模式，不涉及插件开发、自定义脚本或 NetBox 管理。
版本要求：REST API 适用于所有版本；GraphQL API 需 2.9+；v2 Token 需 4.5+（推荐使用）；v1 Token 计划在 4.7+ 弃用，需提前迁移。主要目标为 NetBox 4.4+，v2 Token 特性需 4.5+。
主要能力与规则：认证方面，4.5+ 使用 v2 Token，格式为 Bearer nbt_<key>.<token>，并可通过 provisioning 端点自动创建 Token。REST 方面，列表请求必须分页（?limit=100，最大 1000），部分更新用 PATCH 而非 PUT，列表用 ?brief=True，用 ?fields= 选择字段，设备列表排除 config_context（?exclude=config_context），大规模数据避免 ?q= 搜索，批量操作使用列表端点加 JSON 数组。GraphQL 方面，必须使用 netbox-graphql-query-optimizer，所有列表查询及嵌套层级都要分页，只请求所需字段，深度不超过 3、绝不超 5，注意深层 offset 分页性能问题（4.5.x 可用 ID 范围过滤，4.6.0+ 支持游标分页）。性能方面，排除 config_context、使用 brief 模式、并行化独立请求。数据建模需按依赖顺序创建对象，理解站点与 IPAM 层级，正确使用自定义字段、标签、租户和自然键。
数据写入与分支：高吞吐写入建议使用 Diode 而非直接 API，依赖按名称指定，无需关心创建顺序，Python 可用 pip install netboxlabs-diode-sdk；读取用 REST/GraphQL，写入用 Diode。分支功能需 netbox-branching 插件，生命周期为创建→等待（PROVISIONING→READY）→工作→同步→合并，上下文头为 X-NetBox-Branch: {schema_id}（8 字符 ID），异步操作返回 Job 对象需轮询，所有异步操作支持 {"commit": false} 做干跑验证。
限制：不覆盖插件开发、自定义脚本与管理；分支功能依赖插件；部分规则有版本门槛。具体实现细节与完整规则清单需参考官方文档与技能内附参考文件。