From 39ca11c6626aa08095af2604a8d4b708e493514c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 15 Jan 2014 14:43:34 +0000 Subject: Latest docs build --- api-guide/filtering.html | 20 +++++++++++++++++++- api-guide/serializers.html | 18 ++++++++++++++++++ api-guide/settings.html | 3 +++ 3 files changed, 40 insertions(+), 1 deletion(-) (limited to 'api-guide') diff --git a/api-guide/filtering.html b/api-guide/filtering.html index d2803cb6..f30c9826 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 898b6ea4..1cd7f0dc 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 5a669f43..95f6d114 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'

    -- cgit v1.2.3