Use primary REST API serializers for "brief" mode responses #9282

New Issue

adam · 2025-12-29T20:47:48+01:00

adam commented

2025-12-29 20:47:48 +01:00

Originally created by @jeremystretch on GitHub (Feb 23, 2024).

Originally assigned to: @jeremystretch on GitHub.

Proposed Changes

Currently, NetBox handles "brief" mode requests (e.g. GET /api/dcim/sites/?brief=true) by swapping out the model's primary serializer class with its nested one (e.g. NestedSiteSerializer instead of SiteSerializer). This nested serializer contains a minimal subset of fields from the primary serializer, and exists in the code base as an entirely separate entity.

The proposal here is to use the primary serializer for each model in both normal and brief modes, by defining the relevant fields under the primary serializer's Meta class. For example, the representation defined by the current NestedSiteSerializer class

class NestedSiteSerializer(WritableNestedSerializer):
    url = serializers.HyperlinkedIdentityField(view_name='dcim-api:site-detail')

    class Meta:
        model = models.Site
        fields = ['id', 'url', 'display', 'name', 'slug']

would be reproduced on SiteSerializer as

class SiteSerializer(NetBoxModelSerializer):
    ...
    class Meta:
        model = Site
        fields = [
            'id', 'url', 'display', 'name', 'slug', 'status', 'region', 'group', 'tenant', 'facility', ...
        ]
        brief_fields = ['id', 'url', 'display', 'name', 'slug']

The BriefModeMixin class would no longer be used to dynamically resolve the serializer based on the presence of the brief query parameter; the primary serializer will always be used. Instead, it will leverage the new dynamic fields capability introduced in #15087 to pass the pre-defined brief_fields list to the serializer upon instantiation. This will result in the same rendered data as using the nested serializer.

Justification

This change will enable us to remove nested serializers which exist solely to support brief mode. It does not, however, fully obviate the need for nested serializers, as they are still required in many cases to represent related objects. For example, NestedRegionSerializer is used to represent the Region to which a Site is assigned. (While it may be possible to further reduce our dependency on discrete nested serializer classes, such work is beyond the scope of this initiative.)

Additionally, this work represents the first step toward ultimately deprecating "brief" mode (which is not an immediate goal of this initiative) in favor of the dynamic field specification functionality introduced in #15087.

Originally created by @jeremystretch on GitHub (Feb 23, 2024). Originally assigned to: @jeremystretch on GitHub. ### Proposed Changes Currently, NetBox handles "brief" mode requests (e.g. `GET /api/dcim/sites/?brief=true`) by swapping out the model's primary serializer class with its nested one (e.g. `NestedSiteSerializer` instead of `SiteSerializer`). This nested serializer contains a minimal subset of fields from the primary serializer, and exists in the code base as an entirely separate entity. The proposal here is to use the primary serializer for each model in both normal and brief modes, by defining the relevant fields under the primary serializer's `Meta` class. For example, the representation defined by the current `NestedSiteSerializer` class ```python class NestedSiteSerializer(WritableNestedSerializer): url = serializers.HyperlinkedIdentityField(view_name='dcim-api:site-detail') class Meta: model = models.Site fields = ['id', 'url', 'display', 'name', 'slug'] ``` would be reproduced on `SiteSerializer` as ```python class SiteSerializer(NetBoxModelSerializer): ... class Meta: model = Site fields = [ 'id', 'url', 'display', 'name', 'slug', 'status', 'region', 'group', 'tenant', 'facility', ... ] brief_fields = ['id', 'url', 'display', 'name', 'slug'] ``` The `BriefModeMixin` class would no longer be used to dynamically resolve the serializer based on the presence of the `brief` query parameter; the primary serializer will always be used. Instead, it will leverage the new dynamic fields capability introduced in #15087 to pass the pre-defined `brief_fields` list to the serializer upon instantiation. This will result in the same rendered data as using the nested serializer. ### Justification This change will enable us to remove nested serializers which exist solely to support brief mode. It does **not**, however, fully obviate the need for nested serializers, as they are still required in many cases to represent related objects. For example, `NestedRegionSerializer` is used to represent the Region to which a Site is assigned. (While it may be possible to further reduce our dependency on discrete nested serializer classes, such work is beyond the scope of this initiative.) Additionally, this work represents the first step toward ultimately deprecating "brief" mode (which is **not** an immediate goal of this initiative) in favor of the dynamic field specification functionality introduced in #15087.

adam added the status: accepted type: housekeeping labels 2025-12-29 20:47:48 +01:00

adam closed this issue

2025-12-29 20:47:49 +01:00

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#9282