netbox-rest-api

NetBox REST API Best Practices

Always Paginate (HIGH)

NetBox defaults to 50 items per page (max 1000). Always handle pagination explicitly.

# WRONG: Assumes all results returned
response = requests.get(f"{API_URL}/dcim/devices/", headers=headers)
devices = response.json()["results"]  # Only first 50!

# CORRECT: Paginate through all results
def get_all_objects(endpoint, limit=100):
    all_results = []
    url = f"{API_URL}/{endpoint}/?limit={limit}"
    while url:
        response = requests.get(url, headers=headers)
        data = response.json()
        all_results.extend(data["results"])
        url = data.get("next")
    return all_results

Use Brief Mode for Lists (HIGH)

Reduces payload size significantly for list operations.

# Full nested objects (slow)
response = requests.get(f"{API_URL}/dcim/devices/")

# Brief mode - minimal nested data (fast)
response = requests.get(f"{API_URL}/dcim/devices/?brief=True")

Use Field Selection (HIGH)

For more control than brief mode, specify exactly which fields to include:

# Select specific fields (including nested)
response = requests.get(
    f"{API_URL}/dcim/devices/?fields=id,name,status,site.name,primary_ip4.address"
)

Exclude Expensive Fields (HIGH)

Config context and local context are expensive to compute. Exclude when not needed.

4.5.2+ Use ?omit= Parameter (#21244):

# Exclude multiple expensive fields (4.5.2+)
response = requests.get(
    f"{API_URL}/dcim/devices/",
    params={"omit": "config_context,local_context_data"}
)

The ?omit= parameter is the inverse of ?fields= - include everything except the specified fields.

Pre-4.5.2 Use ?exclude= Parameter:

response = requests.get(
    f"{API_URL}/dcim/devices/",
    params={"exclude": "config_context"}
)

Use PATCH, Not PUT (HIGH)

# WRONG: PUT replaces entire object
requests.put(f"{API_URL}/dcim/devices/123/", json=full_device_data)

# CORRECT: PATCH updates only specified fields
requests.patch(f"{API_URL}/dcim/devices/123/", json={"status": "active"})