Add config options to globally show/hide API fields in list views

[tyler-8]

NetBox version

v4.4.2

Feature type

New functionality

Proposed functionality

Add a new configuration option HIDE_API_LIST_FIELDS that allows NetBox administrators to exclude specific fields from list-view API responses on a per-model basis. This would follow a similar structure to the existing JSON-based Custom Validators configuration.

Example Configuration:

HIDE_API_LIST_FIELDS = {
    "dcim.device": ["config_context", "config_template", "local_context_data"],
    "dcim.site": ["asns"],
    "dcim.rack": ["comments"],
}

(Also allowed via the dynamic configuration feature in the web GUI).

Behavior

• If setting is not defined, default is the existing behavior
• Fields would only be excluded from list views (e.g., /api/dcim/devices/)
• Hidden fields would still be available in:
  • Detail views (e.g., /api/dcim/devices/{id}/)
  • Responses when explicitly included via the ?fields= query parameter
• This configuration would apply instance-wide, reducing payload sizes for all API consumers automatically

Use case

Certain model fields (particularly config_context, config_template, and local_context_data on devices) can add multiple megabytes to a single API list response page, even when using reduced page sizes and filters. While experienced API users can use the ?fields= (or ?exclude=config_context) query parameter to explicitly include only desired fields, this requires:

1. Distributed effort to educate all API consumers
2. Ongoing vigilance to ensure proper optimization
3. Manual intervention for every integration

These large payloads also create infrastructure challenges. Reverse proxies like nginx often resort to temporary file caching when upstream responses exceed their buffer limits, adding disk I/O overhead and latency. While increasing proxy_buffers and proxy_buffer_size can mitigate this, it leads to ballooning memory usage on the web server, especially under concurrent load. This forces administrators to choose between poor performance or excessive resource consumption.

Benefits

1. Improved Performance: Dramatically reduce API response sizes for list endpoints
2. Lower Network Usage: Decrease bandwidth consumption for API integrations
3. Better User Experience: Faster response times without requiring user optimization
4. Centralized Control: Administrators can optimize once rather than coordinating across all API consumers
5. Backward Compatibility: Users needing the hidden fields can still access them via detail endpoints or explicit field selection

Database changes

N/A

External dependencies

N/A

[jeremystretch]

Add a new configuration option HIDE_API_LIST_FIELDS that allows NetBox administrators to exclude specific fields from list-view API responses on a per-model basis.

While I can appreciate the use case, this seems all but guaranteed to result in confusion. API clients will reference the schema & NetBox model documentation, and be understandable confused when not every field is included in an object's serialized representation by default. I don't think this is something we can accept.

Let's break down your points about using the fields query parameter, which was introduced to tackle this.

1. Distributed effort to educate all API consumers

This is the case with the entire API already, no? Admittedly we could do a better job promoting fields as a feature, but this is certainly manageable.

2. Ongoing vigilance to ensure proper optimization

This would also apply to a static configuration parameter.

3. Manual intervention for every integration

Flipping this around, it means that every integration has the flexibility to serve its own needs. A single global configuration would not permit this flexibility.

In summary, I'd be open to proposals in how we can better expose or support the existing dynamic fields functionality, but I'm opposed to implementing any form of static configuration which arbitrarily alters the REST API schema.