Use primary serializers for nested object relationships #9295

New Issue

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

adam commented

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

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

Originally assigned to: @jeremystretch on GitHub.

Proposed Changes

Following the work completed in #15235, it is no longer necessary to define separate nested serializers to represent related objects. We can instead pass an arbitrary list of fields to include when rendering the serialized object.

For example, the Site serializer currently utilizes nested serializers to display the region to which a site is assigned:

class SiteSerializer(NetBoxModelSerializer):
    region = NestedRegionSerializer(  # Nested serializer
        required=False,
        allow_null=True
)

Instead, we can use the primary serializers for each of these related models, passing the specific fields we want the nested representation to include:

class SiteSerializer(NetBoxModelSerializer):
    region = RegionSerializer(  # Primary serializer
        requested_fields=['id', 'url', 'display', 'name', 'slug'],
        required=False,
        allow_null=True
    )

Because the desired set of fields typically matches brief_fields set on the related serializer's Meta class, we can reference it directly. (Passing an arbitrary list of fields where necessary is still possible.)

class SiteSerializer(NetBoxModelSerializer):
    region = RegionSerializer(
        requested_fields=RegionSerializer.Meta.brief_fields,
        required=False,
        allow_null=True
    )

As this approach is a bit verbose, it would be prudent to provide a shortcut in the form of a designated keyword argument when initializing the serializer. For instance, we could pass nested=True to imply that only the serializer's brief_fields should be included. (This would be handled under the base serializer class' __init__() method.)

class SiteSerializer(NetBoxModelSerializer):
    region = RegionSerializer(
        nested=True,
        required=False,
        allow_null=True
    )

Although this change will obviate the need for many of the current nested serializers, IMO we should retain these in the code base for at least one release cycle, to provide a smooth migration path for plugins which may still utilize them.

Justification

This approach provides two substantial benefits. First, it obviates the need to maintain dedicated nested serializers solely for the purpose of representing related objects. For instance, NestedManufacturerSerializer exists only to represent the related manufacturer when viewing a device or module type. With the approach above, it is no longer needed.

Second, we can now include arbitrary fields for additional context. For instance, when representing the site to which a rack is assigned, we might want to include its rack_count, and when representing a device, instead include its device_count.

It's worth noting that this does not automatically negate the need for all nested serializers. There are at least two scenarios where separate serializers must be defined:

When representing recursive hierarchies. For example, RegionSerializer cannot be used to represent a region's parent region.
To avoid circular logic. For example, DeviceSerialzer must represent the virtual chassis to which a device is assigned (if any), yet VirtualChassisSerializer must also represent its master device. A nested serializer must be used in one direction or the other to resolve this circular logic.

Originally created by @jeremystretch on GitHub (Feb 26, 2024). Originally assigned to: @jeremystretch on GitHub. ### Proposed Changes Following the work completed in #15235, it is no longer necessary to define separate nested serializers to represent related objects. We can instead pass an arbitrary list of fields to include when rendering the serialized object. For example, the Site serializer currently utilizes nested serializers to display the region to which a site is assigned: ```python class SiteSerializer(NetBoxModelSerializer): region = NestedRegionSerializer( # Nested serializer required=False, allow_null=True ) ``` Instead, we can use the primary serializers for each of these related models, passing the specific fields we want the nested representation to include: ```python class SiteSerializer(NetBoxModelSerializer): region = RegionSerializer( # Primary serializer requested_fields=['id', 'url', 'display', 'name', 'slug'], required=False, allow_null=True ) ``` Because the desired set of fields typically matches `brief_fields` set on the related serializer's `Meta` class, we can reference it directly. (Passing an arbitrary list of fields where necessary is still possible.) ```python class SiteSerializer(NetBoxModelSerializer): region = RegionSerializer( requested_fields=RegionSerializer.Meta.brief_fields, required=False, allow_null=True ) ``` As this approach is a bit verbose, it would be prudent to provide a shortcut in the form of a designated keyword argument when initializing the serializer. For instance, we could pass `nested=True` to imply that only the serializer's `brief_fields` should be included. (This would be handled under the base serializer class' `__init__()` method.) ```python class SiteSerializer(NetBoxModelSerializer): region = RegionSerializer( nested=True, required=False, allow_null=True ) ``` Although this change will obviate the need for many of the current nested serializers, IMO we should retain these in the code base for at least one release cycle, to provide a smooth migration path for plugins which may still utilize them. ### Justification This approach provides two substantial benefits. First, it obviates the need to maintain dedicated nested serializers solely for the purpose of representing related objects. For instance, `NestedManufacturerSerializer` exists only to represent the related manufacturer when viewing a device or module type. With the approach above, it is no longer needed. Second, we can now include arbitrary fields for additional context. For instance, when representing the site to which a rack is assigned, we might want to include its `rack_count`, and when representing a device, instead include its `device_count`. It's worth noting that this does not automatically negate the need for _all_ nested serializers. There are at least two scenarios where separate serializers must be defined: - When representing recursive hierarchies. For example, `RegionSerializer` cannot be used to represent a region's parent region. - To avoid circular logic. For example, `DeviceSerialzer` must represent the virtual chassis to which a device is assigned (if any), yet `VirtualChassisSerializer` must also represent its master device. A nested serializer must be used in one direction or the other to resolve this circular logic.

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

adam closed this issue

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

Sign in to join this conversation.

Branches Tags

main

21050-device-oob-ip-may-become-orphaned

21102-fix-graphiql-explorer

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#9295