netboxlabs NetBox Integration Code Review
Your knowledge of NetBox APIs may be outdated. Verify specific API behaviors, limits, and patterns against current documentation before flagging issues.
Retrieval Sources
| Source | URL / Method | Use for |
|---|---|---|
| NetBox REST API docs | https://netboxlabs.com/docs/netbox/integrations/rest-api/ |
Current endpoint behavior |
| pynetbox repo | https://github.com/netbox-community/pynetbox |
SDK method signatures |
| Diode Python SDK | https://github.com/netboxlabs/diode-sdk-python |
Ingestion API patterns |
| NetBox MCP server | If configured — verify object schemas and filter availability | Field validation |
Review Workflow
Follow this checklist when reviewing NetBox integration code:
- Verify retrieval — Check current API docs for any endpoints/patterns you're unsure about
- Read the full file — understand the integration's intent before flagging issues
- Check authentication — token format, header usage, credential storage
- Check pagination — all list endpoints must handle pagination
- Check performance — config_context exclusion, brief mode, filter specificity
- Check error handling — HTTP errors, rate limits, timeouts, partial failures
- Check data integrity — correct use of PATCH vs PUT, bulk operation atomicity
- Provide evidence — reference specific line numbers and explain why something is wrong
Critical Rules
Authentication (AUTH)
| ID | Rule | Severity |
|---|---|---|
| AUTH-1 | Use nbt_-prefixed v2 tokens on NetBox 4.5+ |
High |
| AUTH-2 | Never hardcode tokens in source — use env vars or secrets manager | Critical |
| AUTH-3 | Use Bearer prefix in Authorization header (not Token on 4.5+) |
High |
| AUTH-4 | Verify token has required permissions for all accessed endpoints | Medium |
| AUTH-5 | Flag reliance on v1 (Token <plaintext>) tokens — deprecated in 4.6, removed in v5.0; migrate to v2. On 4.6.1+ the v2 plaintext is shown once at creation, so capture it then |
High |
Pagination (PAG)
| ID | Rule | Severity |
|---|---|---|
| PAG-1 | All list endpoint calls MUST handle pagination (follow next links) |
Critical |
| PAG-2 | Never assume all results fit in one response — even small collections grow | High |
| PAG-3 | Set explicit limit parameter — don't rely on server default (50) |
Medium |
| PAG-4 | GraphQL queries MUST include pagination: {limit: N} at every list level |
Critical |
| PAG-5 | Nested GraphQL lists need their own pagination parameters | High |
| PAG-6 | Prefer cursor pagination over deep offsets for large reads — REST ?start=<id> (4.6+), GraphQL pagination: {start: N, limit: M} (4.5.2+); flag deep ?offset= scans |
Medium |
Performance (PERF)
| ID | Rule | Severity |
|---|---|---|
| PERF-1 | Exclude config_context from device/VM list queries (?exclude=config_context) |
Critical |
| PERF-2 | Use ?brief=True for reference lookups and dropdowns |
High |
| PERF-3 | Use specific filters (name__ic=, site_id=) instead of ?q= at scale |
High |
| PERF-4 | Use ?fields= to select only needed fields |
Medium |
| PERF-5 | Parallelize independent API calls — don't serialize unrelated requests | Medium |
| PERF-6 | Use bulk endpoints (POST/PATCH/DELETE arrays) instead of per-object calls | High |
| PERF-7 | GraphQL depth must stay ≤ 3, never exceed 5 | High |
Error Handling (ERR)
| ID | Rule | Severity |
|---|---|---|
| ERR-1 | Handle HTTP 4xx/5xx responses — don't assume success | Critical |
| ERR-2 | Implement retry with backoff for 429 (rate limit) and 5xx errors | High |
| ERR-3 | Handle partial success in bulk operations (all-or-nothing semantics) | Medium |
| ERR-4 | Check response.errors on Diode ingestion responses |
High |
| ERR-5 | Handle branch async job failures (poll until terminal status) | High |
Data Integrity (DATA)
| ID | Rule | Severity |
|---|---|---|
| DATA-1 | Use PATCH for updates — PUT replaces entire objects, clearing omitted fields | Critical |
| DATA-2 | Include id in each object for bulk PATCH/DELETE operations |
High |
| DATA-3 | Use natural keys (slug/name) for readability but be aware of uniqueness constraints | Medium |
| DATA-4 | Validate dependency order for REST creates (parent before child) | High |
| DATA-5 | IPAddress values MUST include CIDR prefix length (/24, not bare IP) |
High |
| DATA-6 | For tag edits, prefer write-only add_tags/remove_tags (4.6+) over read-modify-write of the full tags list — the latter clobbers concurrent writers' tags |
Medium |
| DATA-7 | For read-modify-write on a single object under concurrency, use ETag + If-Match (4.6+); a 412 response means the object changed — re-fetch and retry rather than blind overwrite |
Medium |
Anti-Patterns to Flag
| Anti-Pattern | Why It Matters | Fix |
|---|---|---|
| No pagination loop | Silently drops data beyond first page | Follow next links until null |
?q= for bulk filtering |
Full-text search is slow at scale | Use specific filter expressions |
| PUT for partial updates | Clears fields you didn't intend to change | Use PATCH |
| Hardcoded token in source | Security vulnerability | Use environment variable |
| Sequential single-object creates | 100x slower than bulk | Use array POST to list endpoint |
Ignoring config_context in list queries |
10-100x slower responses | Add ?exclude=config_context |
Catching bare Exception on API calls |
Hides real errors | Catch requests.HTTPError specifically |
| No timeout on HTTP requests | Hangs indefinitely on network issues | Set timeout=30 |
| GraphQL without pagination params | Omitting pagination returns all rows; pagination without limit returns Strawberry's default 100 (not the REST default of 50) — both silently differ from expectations |
Always pass pagination: {limit: N} explicitly |
| Polling branch jobs without backoff | Wastes API calls, may trigger rate limits | Exponential backoff (1s → 30s) |
Scope
This skill covers code that calls NetBox APIs. It does NOT cover:
- NetBox plugin internals → use netbox-plugin-development
- Data model design quality → use netbox-review-datamodel
- NetBox server administration → use netbox-administration
Principles
- Be certain. Retrieve current API docs before flagging version-specific issues.
- Provide evidence. Reference line numbers and explain the actual failure mode.
- Focus on correctness. A working integration that's slightly verbose is better than a broken clever one.
- Severity matters. Critical issues break functionality. High issues degrade performance or reliability. Medium issues affect maintainability.
- Don't over-flag. If code works correctly for its specific use case (e.g., small dataset that fits in one page), note the limitation but don't mark it critical.