Latest docs build

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>

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>

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>

topics/release-notes.html

@@ -225,6 +225,12 @@
 </code></pre>
 <hr />
 <h2 id="23x-series">2.3.x series</h2>
+<h3 id="2312">2.3.12</h3>
+<p><strong>Date</strong>: 15th January 2014</p>
+<ul>
+<li><strong>Security fix</strong>: <code>OrderingField</code> now only allows ordering on readable serializer fields, or on fields explicitly specified using <code>ordering_fields</code>. 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.</li>
+<li>Bugfix: <code>write_only = True</code> fields now display in the browsable API.</li>
+</ul>
 <h3 id="2311">2.3.11</h3>
 <p><strong>Date</strong>: 14th January 2014</p>
 <ul>

tutorial/1-serialization.html

@@ -201,9 +201,8 @@
 <h2 id="setting-up-a-new-environment">Setting up a new environment</h2>
 <p>Before we do anything else we'll create a new virtual environment, using <a href="http://www.virtualenv.org/en/latest/index.html">virtualenv</a>.  This will make sure our package configuration is kept nicely isolated from any other projects we're working on.</p>
 <pre class="prettyprint lang-bsh">
-mkdir ~/env
+virtualenv env
-virtualenv ~/env/tutorial
+source env/bin/activate
-source ~/env/tutorial/bin/activate
 </code></pre>
 <p>Now that we're inside a virtualenv environment, we can install our package requirements.</p>
 <pre class="prettyprint lang-py"><code>pip install django