diff options
Diffstat (limited to 'api-guide')
| -rw-r--r-- | api-guide/filtering.html | 20 | ||||
| -rw-r--r-- | api-guide/serializers.html | 18 | ||||
| -rw-r--r-- | api-guide/settings.html | 3 |
3 files changed, 40 insertions, 1 deletions
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): <p>Multiple orderings may also be specified:</p> <pre class="prettyprint lang-py"><code>http://example.com/api/users?ordering=account,username </code></pre> +<h3 id="specifying-which-fields-may-be-ordered-against">Specifying which fields may be ordered against</h3> +<p>It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an <code>ordering_fields</code> attribute on the view, like so:</p> +<pre class="prettyprint lang-py"><code>class UserListView(generics.ListAPIView): + queryset = User.objects.all() + serializer_class = UserSerializer + filter_backends = (filters.OrderingFilter,) + ordering_fields = ('username', 'email') +</code></pre> +<p>This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data.</p> +<p>If you <em>don't</em> specify an <code>ordering_fields</code> 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 <code>serializer_class</code> attribute.</p> +<p>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 <em>any</em> model field or queryset aggregate, by using the special value <code>'__all__'</code>.</p> +<pre class="prettyprint lang-py"><code>class BookingsListView(generics.ListAPIView): + queryset = Booking.objects.all() + serializer_class = BookingSerializer + filter_backends = (filters.OrderingFilter,) + ordering_fields = '__all__' +</code></pre> +<h3 id="specifying-a-default-ordering">Specifying a default ordering</h3> <p>If an <code>ordering</code> attribute is set on the view, this will be used as the default ordering.</p> <p>Typically you'd instead control this by setting <code>order_by</code> on the initial queryset, but using the <code>ordering</code> 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.</p> <pre class="prettyprint lang-py"><code>class UserListView(generics.ListAPIView): queryset = User.objects.all() - serializer = UserSerializer + serializer_class = UserSerializer filter_backends = (filters.OrderingFilter,) ordering = ('username',) </code></pre> 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') </code></pre> +<h2 id="overiding-the-url-field-behavior">Overiding the URL field behavior</h2> +<p>The name of the URL field defaults to 'url'. You can override this globally, by using the <code>URL_FIELD_NAME</code> setting.</p> +<p>You can also override this on a per-serializer basis by using the <code>url_field_name</code> option on the serializer, like so:</p> +<pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + url_field_name = 'account_url' +</code></pre> +<p><strong>Note</strong>: The generic view implementations normally generate a <code>Location</code> header in response to successful <code>POST</code> requests. Serializers using <code>url_field_name</code> 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 <code>get_success_headers()</code> method.</p> +<p>You can also overide the URL field's view name and lookup field without overriding the field explicitly, by using the <code>view_name</code> and <code>lookup_field</code> options, like so:</p> +<pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + view_name = 'account_detail' + lookup_field='account_name' +</code></pre> <hr /> <h1 id="advanced-serializer-usage">Advanced serializer usage</h1> <p>You can create customized subclasses of <code>ModelSerializer</code> or <code>HyperlinkedModelSerializer</code> that use a different set of default fields.</p> 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 <code>None</code> then generic filtering is disabled.</p> <li><code>exc</code>: The exception.</li> </ul> <p>Default: <code>'rest_framework.views.exception_handler'</code></p> +<h4 id="url_field_name">URL_FIELD_NAME</h4> +<p>A string representing the key that should be used for the URL fields generated by <code>HyperlinkedModelSerializer</code>.</p> +<p>Default: <code>'url'</code></p> <h4 id="format_suffix_kwarg">FORMAT_SUFFIX_KWARG</h4> <p>The name of a parameter in the URL conf that may be used to provide a format suffix.</p> <p>Default: <code>'format'</code></p> |