#17143: Update docs for nested serializer use

docs/development/adding-models.md

@@ -71,7 +71,6 @@ Add the relevant navigation menu items in `netbox/netbox/navigation/menu.py`.
 Create the following for each model:
 
 * Detailed (full) model serializer in `api/serializers.py`
-* Nested serializer in `api/nested_serializers.py`
 * API view in `api/views.py`
 * Endpoint route in `api/urls.py`
 

docs/development/extending-models.md

@@ -50,7 +50,7 @@ If you're adding a relational field (e.g. `ForeignKey`) and intend to include th
 
 ## 5. Update API serializer
 
-Extend the model's API serializer in `<app>.api.serializers` to include the new field. In most cases, it will not be necessary to also extend the nested serializer, which produces a minimal representation of the model.
+Extend the model's API serializer in `<app>.api.serializers` to include the new field.
 
 ## 6. Add fields to forms
 

docs/integrations/rest-api.md

@@ -101,7 +101,7 @@ See the [filtering documentation](../reference/filtering.md) for more details on
 
 ## Serialization
 
-The REST API employs two types of serializers to represent model data: base serializers and nested serializers. The base serializer is used to present the complete view of a model. This includes all database table fields which comprise the model, and may include additional metadata. A base serializer includes relationships to parent objects, but **does not** include child objects. For example, the `VLANSerializer` includes a nested representation its parent VLANGroup (if any), but does not include any assigned Prefixes.
+The REST API generally represents objects in one of two ways: complete or brief. The base serializer is used to present the complete view of an object. This includes all database table fields which comprise the model, and may include additional metadata. A base serializer includes relationships to parent objects, but **does not** include child objects. For example, the `VLANSerializer` includes a nested representation its parent VLANGroup (if any), but does not include any assigned Prefixes. Serializers employ a minimal "brief" representation of related objects, which includes only the attributes prudent for identifying the object.
 
 ```json
 {
@@ -139,7 +139,7 @@ The REST API employs two types of serializers to represent model data: base seri
 
 ### Related Objects
 
-Related objects (e.g. `ForeignKey` fields) are represented using nested serializers. A nested serializer provides a minimal representation of an object, including only its direct URL and enough information to display the object to a user. When performing write API actions (`POST`, `PUT`, and `PATCH`), related objects may be specified by either numeric ID (primary key), or by a set of attributes sufficiently unique to return the desired object.
+Related objects (e.g. `ForeignKey` fields) are included using nested brief representations. This is a minimal representation of an object, including only its direct URL and enough information to display the object to a user. When performing write API actions (`POST`, `PUT`, and `PATCH`), related objects may be specified by either numeric ID (primary key), or by a set of attributes sufficiently unique to return the desired object.
 
 For example, when creating a new device, its rack can be specified by NetBox ID (PK):
 
@@ -151,7 +151,7 @@ For example, when creating a new device, its rack can be specified by NetBox ID
 }
 ```
 
-Or by a set of nested attributes which uniquely identify the rack:
+Or by a set of attributes which uniquely identify the rack:
 
 ```json
 {

docs/plugins/development/rest-api.md

@@ -25,6 +25,8 @@ project-name/
 
 Serializers are responsible for converting Python objects to JSON data suitable for conveying to consumers, and vice versa. NetBox provides the `NetBoxModelSerializer` class for use by plugins to handle the assignment of tags and custom field data. (These features can also be included ad hoc via the `CustomFieldModelSerializer` and `TaggableModelSerializer` classes.)
 
+The default nested representation of an object is defined by the `brief_fields` attributes under the serializer's `Meta` class. (Older versions of NetBox required the definition of a separate nested serializer.)
+
 #### Example
 
 To create a serializer for a plugin model, subclass `NetBoxModelSerializer` in `api/serializers.py`. Specify the model class and the fields to include within the serializer's `Meta` class.
@@ -41,31 +43,7 @@ class MyModelSerializer(NetBoxModelSerializer):
     class Meta:
         model = MyModel
         fields = ('id', 'foo', 'bar', 'baz')
-```
+        brief_fields = ('id', 'url', 'display', 'bar')
-
-### Nested Serializers
-
-There are two cases where it is generally desirable to show only a minimal representation of an object:
-
-1. When displaying an object related to the one being viewed (for example, the region to which a site is assigned)
-2. Listing many objects using "brief" mode
-
-To accommodate these, it is recommended to create nested serializers accompanying the "full" serializer for each model. NetBox provides the `WritableNestedSerializer` class for just this purpose. This class accepts a primary key value on write, but displays an object representation for read requests. It also includes a read-only `display` attribute which conveys the string representation of the object.
-
-#### Example
-
-```python
-# api/serializers.py
-from rest_framework import serializers
-from netbox.api.serializers import WritableNestedSerializer
-from my_plugin.models import MyModel
-
-class NestedMyModelSerializer(WritableNestedSerializer):
-    foo = SiteSerializer(nested=True, allow_null=True)
-
-    class Meta:
-        model = MyModel
-        fields = ('id', 'display', 'foo')
 ```
 
 ## Viewsets