Multiple orderings may also be specified:
http://example.com/api/users?ordering=account,username
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__'
+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',)
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'
+You can create customized subclasses of ModelSerializer or HyperlinkedModelSerializer that use a different set of default fields.
None then generic filtering is disabled.
exc: The exception.Default: 'rest_framework.views.exception_handler'
A string representing the key that should be used for the URL fields generated by HyperlinkedModelSerializer.
Default: 'url'
The name of a parameter in the URL conf that may be used to provide a format suffix.
Default: 'format'
Date: 15th January 2014
+OrderingField now only allows ordering on readable serializer fields, or on fields explicitly specified using ordering_fields. This prevents users being able to order by fields that are not visible in the API, and exploiting the ordering of sensitive data such as password hashes.write_only = True fields now display in the browsable API.Date: 14th January 2014
Before we do anything else we'll create a new virtual environment, using virtualenv. This will make sure our package configuration is kept nicely isolated from any other projects we're working on.
-mkdir ~/env -virtualenv ~/env/tutorial -source ~/env/tutorial/bin/activate +virtualenv env +source env/bin/activate
Now that we're inside a virtualenv environment, we can install our package requirements.
pip install django