Third Party Packages
@@ -561,6 +577,11 @@ class Track(models.Model):
}
By default this field is read-write, although you can change this behavior using the read_only flag.
+
+Note: This field is designed for objects that map to a URL that accepts a single URL keyword argument, as set using the lookup_field and lookup_url_kwarg arguments.
+This is suitable for URLs that contain a single primary key or slug argument as part of the URL.
+If you require more complex hyperlinked representation you'll need to customize the field, as described in the custom hyperlinked fields section, below.
+
Arguments:
{
+>>> album = Album.objects.create(album_name="The Grey Album", artist='Danger Mouse')
+>>> Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)
+<Track: Track object>
+>>> Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)
+<Track: Track object>
+>>> Track.objects.create(album=album, order=3, title='Encore', duration=159)
+<Track: Track object>
+>>> serializer = AlbumSerializer(instance=album)
+>>> serializer.data
+{
'album_name': 'The Grey Album',
'artist': 'Danger Mouse',
'tracks': [
- {'order': 1, 'title': 'Public Service Announcement'},
- {'order': 2, 'title': 'What More Can I Say'},
- {'order': 3, 'title': 'Encore'},
+ {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
+ {'order': 2, 'title': 'What More Can I Say', 'duration': 264},
+ {'order': 3, 'title': 'Encore', 'duration': 159},
...
],
}
+Writable nested serializers
+Be default nested serializers are read-only. If you want to to support write-operations to a nested serializer field you'll need to create either or both of the create() and/or update() methods, in order to explicitly specify how the child relationships should be saved.
+class TrackSerializer(serializers.ModelSerializer):
+ class Meta:
+ model = Track
+ fields = ('order', 'title')
+
+class AlbumSerializer(serializers.ModelSerializer):
+ tracks = TrackSerializer(many=True)
+
+ class Meta:
+ model = Album
+ fields = ('album_name', 'artist', 'tracks')
+
+ def create(self, validated_data):
+ tracks_data = validated_data.pop('tracks')
+ album = Album.objects.create(**validated_data)
+ for track_data in tracks_data:
+ Track.objects.create(album=album, **track_data)
+ return album
+
+>>> data = {
+ 'album_name': 'The Grey Album',
+ 'artist': 'Danger Mouse',
+ 'tracks': [
+ {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
+ {'order': 2, 'title': 'What More Can I Say', 'duration': 264},
+ {'order': 3, 'title': 'Encore', 'duration': 159},
+ ],
+}
+>>> serializer = AlbumSerializer(data=data)
+>>> serializer.is_valid()
+True
+>>> serializer.save()
+<Album: Album object>
+
Custom relational fields
To implement a custom relational field, you should override RelatedField, and implement the .to_representation(self, value) method. This method takes the target of the field as the value argument, and should return the representation that should be used to serialize the target. The value argument will typically be a model instance.
If you want to implement a read-write relational field, you must also implement the .to_internal_value(self, data) method.
@@ -692,6 +758,48 @@ class AlbumSerializer(serializers.ModelSerializer):
}
+Custom hyperlinked fields
+In some cases you may need to customize the behavior of a hyperlinked field, in order to represent URLs that require more than a single lookup field.
+You can achieve this by overriding HyperlinkedRelatedField. There are two methods that may be overridden:
+get_url(self, obj, view_name, request, format)
+The get_url method is used to map the object instance to its URL representation.
+May raise a NoReverseMatch if the view_name and lookup_field
+attributes are not configured to correctly match the URL conf.
+get_object(self, queryset, view_name, view_args, view_kwargs)
+If you want to support a writable hyperlinked field then you'll also want to override get_object, in order to map incoming URLs back to the object they represent. For read-only hyperlinked fields there is no need to override this method.
+The return value of this method should the object that corresponds to the matched URL conf arguments.
+May raise an ObjectDoesNotExist exception.
+Example
+Say we have a URL for a customer object that takes two keyword arguments, like so:
+/api/<organization_slug>/customers/<customer_pk>/
+
+This cannot be represented with the default implementation, which accepts only a single lookup field.
+In this case we'd need to override HyperlinkedRelatedField to get the behavior we want:
+from rest_framework import serializers
+from rest_framework.reverse import reverse
+
+class CustomerHyperlink(serializers.HyperlinkedRelatedField):
+ # We define these as class attributes, so we don't need to pass them as arguments.
+ view_name = 'customer-detail'
+ queryset = Customer.objects.all()
+
+ def get_url(self, obj, view_name, request, format):
+ url_kwargs = {
+ 'organization_slug': obj.organization.slug,
+ 'customer_pk': obj.pk
+ }
+ return reverse(view_name, url_kwargs, request=request, format=format)
+
+ def get_object(self, view_name, view_args, view_kwargs):
+ lookup_kwargs = {
+ 'organization__slug': view_kwargs['organization_slug'],
+ 'pk': view_kwargs['customer_pk']
+ }
+ return self.get_queryset().get(**lookup_kwargs)
+
+Note that if you wanted to use this style together with the generic views then you'd also need to override .get_object on the view in order to get the correct lookup behavior.
+Generally we recommend a flat style for API representations where possible, but the nested URL style can also be reasonable when used in moderation.
+
Further notes
The queryset argument
The queryset argument is only ever required for writable relationship field, in which case it is used for performing the model instance lookup, that maps from the primitive user input, into a model instance.
@@ -787,28 +895,6 @@ class Note(models.Model):
If you explicitly specify a relational field pointing to a
ManyToManyField with a through model, be sure to set read_only
to True.
-Advanced Hyperlinked fields
-If you have very specific requirements for the style of your hyperlinked relationships you can override HyperlinkedRelatedField.
-There are two methods you'll need to override.
-
-This method should return the URL that corresponds to the given object.
-May raise a NoReverseMatch if the view_name and lookup_field
-attributes are not configured to correctly match the URL conf.
-get_object(self, queryset, view_name, view_args, view_kwargs)
-This method should the object that corresponds to the matched URL conf arguments.
-May raise an ObjectDoesNotExist exception.
-Example
-For example, if all your object URLs used both a account and a slug in the the URL to reference the object, you might create a custom field like this:
-class CustomHyperlinkedField(serializers.HyperlinkedRelatedField):
- def get_url(self, obj, view_name, request, format):
- kwargs = {'account': obj.account, 'slug': obj.slug}
- return reverse(view_name, kwargs=kwargs, request=request, format=format)
-
- def get_object(self, queryset, view_name, view_args, view_kwargs):
- account = view_kwargs['account']
- slug = view_kwargs['slug']
- return queryset.get(account=account, slug=slug)
-
Third Party Packages
The following third party packages are also available.
diff --git a/api-guide/renderers/index.html b/api-guide/renderers/index.html
index 7ae110a31..9030c9ff2 100644
--- a/api-guide/renderers/index.html
+++ b/api-guide/renderers/index.html
@@ -277,6 +277,10 @@
3.1 Announcement
+