From 39ca11c6626aa08095af2604a8d4b708e493514c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 15 Jan 2014 14:43:34 +0000 Subject: [PATCH] Latest docs build --- api-guide/filtering.html | 20 +++++++++++++++++++- api-guide/serializers.html | 18 ++++++++++++++++++ api-guide/settings.html | 3 +++ topics/release-notes.html | 6 ++++++ tutorial/1-serialization.html | 5 ++--- 5 files changed, 48 insertions(+), 4 deletions(-) diff --git a/api-guide/filtering.html b/api-guide/filtering.html index d2803cb63..f30c9826d 100644 --- a/api-guide/filtering.html +++ b/api-guide/filtering.html @@ -420,11 +420,29 @@ class ProductFilter(django_filters.FilterSet):

Multiple orderings may also be specified:

http://example.com/api/users?ordering=account,username
+

Specifying which fields may be ordered against

+

It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an ordering_fields attribute on the view, like so:

+
class UserListView(generics.ListAPIView):
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+    filter_backends = (filters.OrderingFilter,)
+    ordering_fields = ('username', 'email')
+
+

This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.

+

If you don't specify an ordering_fields attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the serializer_class attribute.

+

If you are confident that the queryset being used by the view doesn't contain any sensitive data, you can also explicitly specify that a view should allow ordering on any model field or queryset aggregate, by using the special value '__all__'.

+
class BookingsListView(generics.ListAPIView):
+    queryset = Booking.objects.all()
+    serializer_class = BookingSerializer
+    filter_backends = (filters.OrderingFilter,)
+    ordering_fields = '__all__'
+
+

Specifying a default ordering

If an ordering attribute is set on the view, this will be used as the default ordering.

Typically you'd instead control this by setting order_by on the initial queryset, but using the ordering parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template. This makes it possible to automatically render column headers differently if they are being used to order the results.

class UserListView(generics.ListAPIView):
     queryset = User.objects.all()
-    serializer = UserSerializer
+    serializer_class = UserSerializer
     filter_backends = (filters.OrderingFilter,)
     ordering = ('username',)
diff --git a/api-guide/serializers.html b/api-guide/serializers.html index 898b6ea4a..1cd7f0dc6 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -565,6 +565,24 @@ def restore_object(self, attrs, instance=None): model = Account fields = ('url', 'account_name', 'users', 'created') +

Overiding the URL field behavior

+

The name of the URL field defaults to 'url'. You can override this globally, by using the URL_FIELD_NAME setting.

+

You can also override this on a per-serializer basis by using the url_field_name option on the serializer, like so:

+
class AccountSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Account
+        fields = ('account_url', 'account_name', 'users', 'created')
+        url_field_name = 'account_url'
+
+

Note: The generic view implementations normally generate a Location header in response to successful POST requests. Serializers using url_field_name option will not have this header automatically included by the view. If you need to do so you will ned to also override the view's get_success_headers() method.

+

You can also overide the URL field's view name and lookup field without overriding the field explicitly, by using the view_name and lookup_field options, like so:

+
class AccountSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Account
+        fields = ('account_url', 'account_name', 'users', 'created')
+        view_name = 'account_detail'
+        lookup_field='account_name'
+

Advanced serializer usage

You can create customized subclasses of ModelSerializer or HyperlinkedModelSerializer that use a different set of default fields.

diff --git a/api-guide/settings.html b/api-guide/settings.html index 5a669f434..95f6d114a 100644 --- a/api-guide/settings.html +++ b/api-guide/settings.html @@ -408,6 +408,9 @@ If set to None then generic filtering is disabled.

  • exc: The exception.

    • Default: 'rest_framework.views.exception_handler'

    +

    URL_FIELD_NAME

    +

    A string representing the key that should be used for the URL fields generated by HyperlinkedModelSerializer.

    +

    Default: 'url'

    FORMAT_SUFFIX_KWARG

    The name of a parameter in the URL conf that may be used to provide a format suffix.

    Default: 'format'

    diff --git a/topics/release-notes.html b/topics/release-notes.html index e6797a764..91ed440eb 100644 --- a/topics/release-notes.html +++ b/topics/release-notes.html @@ -225,6 +225,12 @@

    2.3.x series

    +

    2.3.12

    +

    Date: 15th January 2014

    +

    2.3.11

    Date: 14th January 2014