netbox-review-integration

NetBox 統合コードレビュー

NetBox API に関する知識が古くなっている可能性があります。 問題を指摘する前に、具体的な API の動作、制限、パターンを最新のドキュメントで確認してください。

対象： NetBox 4.5～4.7（現行バージョンは 4.7.3）。一部のルールは 4.6 と 4.7 の間で切り替わります。バージョン別のルールを適用する前に、対象バージョンを確認してください（GET /api/status/ → netbox-version、またはプロジェクトの固定バージョン）。

情報取得元

情報源	URL ／ 方法	用途
NetBox REST API ドキュメント	https://netboxlabs.com/docs/netbox/integrations/rest-api/	現在のエンドポイントの動作
pynetbox リポジトリ	https://github.com/netbox-community/pynetbox	SDK のメソッドシグネチャ
Diode Python SDK	https://github.com/netboxlabs/diode-sdk-python	取り込み API のパターン
NetBox MCP サーバー	設定されている場合 — オブジェクトスキーマとフィルターの利用可否を確認	フィールドの検証

レビューワークフロー

NetBox 統合コードをレビューする際は、次のチェックリストに従ってください。

1. 情報取得を確認する — 確信が持てないエンドポイントやパターンについて、最新の API ドキュメントを確認します
2. ファイル全体を読む — 問題を指摘する前に、統合の意図を理解します
3. 認証を確認する — トークン形式、ヘッダーの使用方法、認証情報の保存方法を確認します
4. ページネーションを確認する — すべてのリストエンドポイントでページネーションに対応していることを確認します
5. パフォーマンスを確認する — config_context の扱い（バージョン依存）、簡易モード／フィールド選択、フィルターの具体性を確認します
6. エラー処理を確認する — HTTP エラー、レート制限、タイムアウト、部分的な失敗を確認します
7. データの整合性を確認する — PATCH と PUT の正しい使い分け、一括操作の原子性を確認します
8. 根拠を示す — 該当する行番号を参照し、問題である理由を説明します

重要なルール

認証（AUTH）

ID	ルール	重大度
AUTH-1	NetBox 4.5 以降では、nbt_ 接頭辞付きの v2 トークンを使用します	高
AUTH-2	ソースコードにトークンをハードコードしないでください。環境変数またはシークレットマネージャーを使用します	重大
AUTH-3	Authorization ヘッダーには Bearer 接頭辞を使用します（4.5 以降では Token ではありません）	高
AUTH-4	アクセスするすべてのエンドポイントに必要な権限がトークンにあることを確認します	中
AUTH-5	v1（Token <plaintext>）トークンへの依存を指摘してください。4.6 で非推奨となり、v5.0 で削除されます。v2 に移行してください。4.6.1 以降では、v2 のプレーンテキストは作成時に一度だけ表示され、レスポンスの token フィールドに含まれます（key は公開識別子にすぎません）。その時点で取得してください	高
AUTH-6	?background=true を指定してトークンを作成しないでください（4.7.0／4.7.1 ではジョブ結果にプレーンテキストが記録され、4.7.2 では 400 が返されます）。また、作成時にクライアントが指定した token 値に依存しないでください（4.7 以降では無視されます）	高
AUTH-7	4.7 以降では、POST /api/extras/scripts/<id>/ によるカスタムスクリプトの実行に書き込み可能なトークンが必要です。読み取り専用トークンを使用している場合は指摘してください	中

ページネーション（PAG）

ID	ルール	重大度
PAG-1	すべてのリストエンドポイント呼び出しでページネーションに対応しなければなりません（next リンクをたどる）	重大
PAG-2	すべての結果が 1 回のレスポンスに収まると想定しないでください。小規模なコレクションも増加します	高
PAG-3	limit パラメーターを明示的に設定してください。サーバーのデフォルト値（50）に依存しないでください	中
PAG-4	GraphQL クエリでは、すべてのリスト階層に pagination: {limit: N} を含めなければなりません	重大
PAG-5	ネストされた GraphQL リストには、それぞれ独自のページネーションパラメーターが必要です	高
PAG-6	大規模なデータ読み取りでは、深いオフセットよりカーソルページネーションを優先してください。REST の ?start=<id>（4.6 以降）、GraphQL の pagination: {start: N, limit: M}（4.5.2 以降）を使用し、深い ?offset= による走査は指摘してください	中

パフォーマンス（PERF）

ID	ルール	重大度
PERF-1	4.5–4.6： デバイス／VM のリストクエリでは、?omit=config_context（4.5.2+）または ?exclude=config_context を必ず送信します。4.7.0–4.7.2： config context はキャッシュされ、常に読み込まれます。?exclude= は警告なしで無視されるため、指定されていないことを問題として指摘しないでください。ペイロードサイズのためにこれに依存するコードを指摘し、?fields=／?omit=／?brief=True を提案してください。4.7.3+： ?omit=config_context／?fields=／?brief=True により config context の DB アノテーションが再びスキップされます。読み取ることのない config_context を読み込むリスト読み取りを指摘してください。?exclude= はすべての 4.7.x で何もしません。バージョンをまたいで使える形式は ?omit=config_context です	Critical（4.5–4.6）／Low（4.7.0–4.7.2）／Medium（4.7.3+）
PERF-2	参照検索やドロップダウンには ?brief=True を使用します	High
PERF-3	大規模な環境では、?q= ではなく具体的なフィルター（name__ic=、site_id=）を使用します	High
PERF-4	必要なフィールドのみを選択するには ?fields= を使用します	Medium
PERF-5	独立した API 呼び出しは並列化し、無関係なリクエストを直列化しないでください	Medium
PERF-6	オブジェクトごとの呼び出しではなく、一括エンドポイント（POST/PATCH/DELETE 配列）を使用します	High
PERF-7	GraphQL の深さは 3 以下に保ち、5 を超えないようにしてください	High

エラー処理（ERR）

ID	ルール	重大度
ERR-1	HTTP 4xx/5xx レスポンスを処理し、成功したと決めつけないでください	Critical
ERR-2	429（レート制限）および 5xx エラーに対して、バックオフ付きの再試行を実装します	High
ERR-3	一括処理の失敗を処理します。すべてのバージョンで一括処理は全件成功か全件失敗です。4.7+ では、本文は {"detail", "errors": [{"index" or "id", "errors"}]} です。エラーを送信したオブジェクトに対応付け（作成および形式不正の項目には index、更新／削除には id を使用）、該当する項目のみ再送信してください。4.5–4.6 では、最初の失敗に対するフィールドエラーのみが返されます	Medium
ERR-4	Diode の取り込みレスポンスで response.errors を確認します	High
ERR-5	ブランチの非同期ジョブの失敗を処理します（終端ステータスになるまでポーリングします）	High
ERR-6	?background=true（4.7+）：202 は受け付けられたことを示すものであり、成功したことを示すものではありません。コードは job.url を終端ステータスになるまでポーリングし、data.status_code を確認する必要があります。202 を成功として扱うこと、If-Match とバックグラウンド処理の併用（400）、503 の処理漏れ（ワーカーなし）、および 4.7.0–4.7.2 での ?background=true と X-NetBox-Branch の併用（ヘッダーが破棄され、書き込みがメインに反映される。4.7.3 で修正）を指摘してください	High

データ整合性（DATA）

ID	ルール	重大度
DATA-1	更新には PATCH を使用します。PUT はオブジェクト全体を置き換え、省略されたフィールドをクリアします	Critical
DATA-2	一括 PATCH/DELETE 操作では、各オブジェクトに id を含めます	High
DATA-3	可読性のために自然キー（slug/name）を使用しますが、一意性制約に注意してください	Medium
DATA-4	REST で作成する際、依存関係の順序（子より先に親）を検証します	High
DATA-5	IPAddress の値には CIDR プレフィックス長（単独の IP ではなく /24）を必ず含めます	High
DATA-6	タグを編集する場合、tags リスト全体の読み取り・変更・書き戻しよりも、書き込み専用の add_tags／remove_tags（4.6+）を優先します。後者は、並行して書き込む処理のタグを上書きします	Medium
DATA-7	単一オブジェクトを並行実行下で読み取り・変更・書き戻しする場合は、ETag と If-Match（4.6+）を使用します。412 レスポンスはオブジェクトが変更されたことを意味します。無条件に上書きするのではなく、再取得して再試行してください	Medium
DATA-8	4.7+ では、選択／複数選択のカスタムフィールドは {"value", "label"} オブジェクトとして読み取られます。custom_fields["x"] == "raw" の比較や、読み取ったオブジェクトを書き戻すコード（検証に失敗します）を指摘し、raw 値を書き込むようにしてください	High
DATA-9	Services：4.7+ では、非推奨の protocol／ports の組み合わせよりも port_mappings（["tcp/80"]）を使用します（5.0 で削除）。protocol__ic 形式や port__empty フィルター（4.7 で廃止）を指摘してください	Medium

フラグを立てるべきアンチパターン

アンチパターン	重要な理由	修正方法
ページネーションのループがない	2ページ目以降のデータが気付かないうちに欠落します	next のリンクをたどり、null になるまで続けます
一括フィルタリングに ?q= を使う	大規模環境では全文検索が遅くなります	具体的なフィルター式を使います
部分更新に PUT を使う	変更するつもりのないフィールドがクリアされます	PATCH を使います
ソースコードにトークンをハードコードする	セキュリティ上の脆弱性になります	環境変数を使います
単一オブジェクトを順番に作成する	一括処理より100倍遅くなります	リストエンドポイントに配列を POST します
使用しないリストクエリで config_context を読み込む	4.5〜4.6では10〜100倍遅くなり、4.7.3以降では追加のDBアノテーションが発生します。4.7.0〜4.7.2でのみペイロードが肥大化します	?omit=config_context を追加します（4.5.2以降で使用可能。バージョン間で移植可能）。?exclude= は4.5〜4.6でのみ機能し、4.7.xではすべて無視されます
?background=true の HTTP 202 を成功として扱う（4.7以降）	検証と書き込みは後でワーカー内で実行されます	ジョブ URL をポーリングし、status と data.status_code を確認します
4.7以降で custom_fields["env"] == "prod" を使う	選択値は {"value", "label"} 形式の辞書のため、比較は常に False になります	["value"] と比較します。4.6/4.7が混在する環境では、防御的に値を取り出します
?background=true を使って API トークンを作成する	平文がジョブの結果に含まれます（4.7.0/4.7.1）。4.7.2以降では400エラーになります	トークンは同期的に作成します。4.7.3以降を実行してください（4.7.0/4.7.1ではトークンが漏えいします。4.7.3ではブランチに対応したバックグラウンド書き込みと、config-context の省略最適化が追加されます）
4.7.0〜4.7.2で X-NetBox-Branch とともに ?background=true を送信する	ワーカーでブランチヘッダーが破棄され、一括書き込みがメインに反映されます（または Changes の protect_main によって拒否されます）	4.7.2以前ではブランチコンテキスト内で同期的に一括書き込みを行います。4.7.3以降では正しく引き継がれます
API 呼び出しで無条件の Exception を捕捉する	実際のエラーが隠れてしまいます	requests.HTTPError を明示的に捕捉します
HTTP リクエストにタイムアウトを設定しない	ネットワークの問題が発生すると、無期限に停止します	timeout=30 を設定します
ページネーションパラメーターなしで GraphQL を使う	pagination を省略するとすべての行が返されます。limit を指定せずに pagination を使うと、Strawberry のデフォルトである100件が返されます（REST のデフォルトは50件です）。どちらの場合も、想定と異なる結果が気付かないうちに返されます	常に pagination: {limit: N} を明示的に渡します
バックオフなしでブランチのジョブをポーリングする	API 呼び出しを浪費し、レート制限を引き起こす可能性があります	指数バックオフを使います（1秒 → 30秒）

バージョンに関する注意

NetBox 4.7.3（2026-10-13）

• PERF-1 の重大度は Medium に上がります。?omit=config_context／?fields=／?brief=True により、config-context の DB アノテーションが再びスキップされます（?exclude= は引き続き何もしません）。ERR-6 のブランチに関する注意点は解消されます。?background=true が X-NetBox-Branch をワーカーに引き継ぐようになりました。4.7.3以降を推奨します（4.7.0/4.7.1ではトークンが漏えいします。4.7.3ではブランチに対応したバックグラウンド書き込みと、config-context の省略最適化が追加されます）。

対象範囲

このスキルの対象は、NetBox API を呼び出すコードです。以下は対象外です。

• NetBox プラグインの内部実装 → netbox-plugin-development を使います
• データモデル設計の品質 → netbox-review-datamodel を使います
• NetBox サーバーの管理 → netbox-administration を使います

原則

• 確実性を重視します。 バージョン固有の問題を指摘する前に、最新の API ドキュメントを取得します。
• 根拠を示します。 行番号を参照し、実際にどのような障害が起きるのかを説明します。
• 正確性を重視します。 少し冗長でも動作するインテグレーションのほうが、巧妙でも壊れているものより優れています。
• 重大度は重要です。 Critical の問題は機能を壊します。High の問題はパフォーマンスや信頼性を低下させます。Medium の問題は保守性に影響します。
• 過剰に指摘しないでください。 特定のユースケース（例：1ページに収まる小規模なデータセット）でコードが正しく動作する場合は、制限事項に触れつつ、重大な問題として扱わないでください。