starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

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

New Issue
Closed
opened 2025-12-29 21:48:32 +01:00 by adam · 1 comment
adam commented 2025-12-29 21:48:32 +01:00
Owner
Copy Link

Originally created by @tyler-8 on GitHub (Oct 2, 2025).

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

Originally created by @tyler-8 on GitHub (Oct 2, 2025). ### 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: ```python 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
adam added the type: featurenetbox labels 2025-12-29 21:48:33 +01:00
adam closed this issue 2025-12-29 21:48:33 +01:00
adam commented 2025-12-29 21:48:33 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 9, 2025):

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.

  1. Ongoing vigilance to ensure proper optimization

This would also apply to a static configuration parameter.

  1. 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.

@jeremystretch commented on GitHub (Oct 9, 2025): > 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.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label netbox type: feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#11678
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?