9 files changed, 70 insertions, 5 deletions
diff --git a/api-guide/authentication/index.html b/api-guide/authentication/index.html
index a41c7bb0..ac8f4629 100644
--- a/api-guide/authentication/index.html
+++ b/api-guide/authentication/index.html
@@ -487,7 +487,7 @@
 <p>If no class authenticates, <code>request.user</code> will be set to an instance of <code>django.contrib.auth.models.AnonymousUser</code>, and <code>request.auth</code> will be set to <code>None</code>.</p>
 <p>The value of <code>request.user</code> and <code>request.auth</code> for unauthenticated requests can be modified using the <code>UNAUTHENTICATED_USER</code> and <code>UNAUTHENTICATED_TOKEN</code> settings.</p>
 <h2 id="setting-the-authentication-scheme">Setting the authentication scheme</h2>
-<p>The default authentication schemes may be set globally, using the <code>DEFAULT_AUTHENTICATION</code> setting.  For example.</p>
+<p>The default authentication schemes may be set globally, using the <code>DEFAULT_AUTHENTICATION_CLASSES</code> setting.  For example.</p>
 <pre><code>REST_FRAMEWORK = {
     'DEFAULT_AUTHENTICATION_CLASSES': (
         'rest_framework.authentication.BasicAuthentication',
@@ -672,7 +672,7 @@ python manage.py createsuperuser
     'provider.oauth2',
 )
 </code></pre>
-<p>Then add <code>OAuth2Authentication</code> to your global <code>DEFAULT_AUTHENTICATION</code> setting:</p>
+<p>Then add <code>OAuth2Authentication</code> to your global <code>DEFAULT_AUTHENTICATION_CLASSES</code> setting:</p>
 <pre><code>'DEFAULT_AUTHENTICATION_CLASSES': (
     'rest_framework.authentication.OAuth2Authentication',
 ),
diff --git a/api-guide/exceptions/index.html b/api-guide/exceptions/index.html
index a0734a14..f9403f1d 100644
--- a/api-guide/exceptions/index.html
+++ b/api-guide/exceptions/index.html
@@ -442,7 +442,7 @@
 <li>Django's <code>PermissionDenied</code> exception.</li>
 </ul>
 <p>In each case, REST framework will return a response with an appropriate status code and content-type.  The body of the response will include any additional details regarding the nature of the error.</p>
-<p>By default all error responses will include a key <code>detail</code> in the body of the response, but other keys may also be included.</p>
+<p>Most error responses will include a key <code>detail</code> in the body of the response.</p>
 <p>For example, the following request:</p>
 <pre><code>DELETE http://api.example.com/foo/bar HTTP/1.1
 Accept: application/json
@@ -454,6 +454,14 @@ Content-Length: 42
 
 {"detail": "Method 'DELETE' not allowed."}
 </code></pre>
+<p>Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the "non_field_errors" key, or whatever string value has been set for the <code>NON_FIELD_ERRORS_KEY</code> setting.</p>
+<p>Any example validation error might look like this:</p>
+<pre><code>HTTP/1.1 400 Bad Request
+Content-Type: application/json
+Content-Length: 94
+
+{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
+</code></pre>
 <h2 id="custom-exception-handling">Custom exception handling</h2>
 <p>You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects.  This allows you to control the style of error responses used by your API.</p>
 <p>The function must take a single argument, which is the exception to be handled, and should either return a <code>Response</code> object, or return <code>None</code> if the exception cannot be handled.  If the handler returns <code>None</code> then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.</p>
diff --git a/api-guide/fields/index.html b/api-guide/fields/index.html
index aedc4ea1..9cac530a 100644
--- a/api-guide/fields/index.html
+++ b/api-guide/fields/index.html
@@ -595,6 +595,7 @@
 <h3 id="required"><code>required</code></h3>
 <p>Normally an error will be raised if a field is not supplied during deserialization.
 Set to false if this field is not required to be present during deserialization.</p>
+<p>Setting this to <code>False</code> also allows the object attribute or dictionary key to be omitted from output when serializing the instance. If the key is not present it will simply not be included in the output representation.</p>
 <p>Defaults to <code>True</code>.</p>
 <h3 id="allow_null"><code>allow_null</code></h3>
 <p>Normally an error will be raised if <code>None</code> is passed to a serializer field. Set this keyword argument to <code>True</code> if <code>None</code> should be considered a valid value.</p>
@@ -879,7 +880,7 @@ class UserSerializer(serializers.ModelSerializer):
 
 class ColorField(serializers.Field):
     """
-    Color objects are serialized into "rgb(#, #, #)" notation.
+    Color objects are serialized into 'rgb(#, #, #)' notation.
     """
     def to_representation(self, obj):
         return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue)
diff --git a/api-guide/filtering/index.html b/api-guide/filtering/index.html
index 6a55b999..fa0a15f8 100644
--- a/api-guide/filtering/index.html
+++ b/api-guide/filtering/index.html
@@ -702,6 +702,7 @@ class ProductFilter(django_filters.FilterSet):
     queryset = User.objects.all()
     serializer_class = UserSerializer
     filter_backends = (filters.OrderingFilter,)
+    ordering_fields = ('username', 'email')
     ordering = ('username',)
 </code></pre>
 <p>The <code>ordering</code> attribute may be either a string or a list/tuple of strings.</p>
diff --git a/api-guide/format-suffixes/index.html b/api-guide/format-suffixes/index.html
index 22181b1b..d7d74db9 100644
--- a/api-guide/format-suffixes/index.html
+++ b/api-guide/format-suffixes/index.html
@@ -428,6 +428,16 @@ def comment_list(request, format=None):
 </code></pre>
 <p>The name of the kwarg used may be modified by using the <code>FORMAT_SUFFIX_KWARG</code> setting.</p>
 <p>Also note that <code>format_suffix_patterns</code> does not support descending into <code>include</code> URL patterns.</p>
+<h3 id="using-with-i18n_patterns">Using with <code>i18n_patterns</code></h3>
+<p>If using the <code>i18n_patterns</code> function provided by Django, as well as <code>format_suffix_patterns</code> you should make sure that the <code>i18n_patterns</code> function is applied as the final, or outermost function. For example:</p>
+<pre><code>url patterns = [
+    …
+]
+
+urlpatterns = i18n_patterns(
+    format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
+)
+</code></pre>
 <hr />
 <h2 id="accept-headers-vs-format-suffixes">Accept headers vs. format suffixes</h2>
 <p>There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that <code>HTTP Accept</code> headers should always be used instead.</p>
diff --git a/api-guide/generic-views/index.html b/api-guide/generic-views/index.html
index 18910b4e..675220d7 100644
--- a/api-guide/generic-views/index.html
+++ b/api-guide/generic-views/index.html
@@ -666,6 +666,7 @@ class UserList(generics.ListCreateAPIView):
 <hr />
 <h1 id="mixins">Mixins</h1>
 <p>The mixin classes provide the actions that are used to provide the basic view behavior.  Note that the mixin classes provide action methods rather than defining the handler methods, such as <code>.get()</code> and <code>.post()</code>, directly.  This allows for more flexible composition of behavior.</p>
+<p>The mixin classes can be imported from <code>rest_framework.mixins</code>.</p>
 <h2 id="listmodelmixin">ListModelMixin</h2>
 <p>Provides a <code>.list(request, *args, **kwargs)</code> method, that implements listing a queryset.</p>
 <p>If the queryset is populated, this returns a <code>200 OK</code> response, with a serialized representation of the queryset as the body of the response.  The response data may optionally be paginated.</p>
@@ -688,6 +689,7 @@ class UserList(generics.ListCreateAPIView):
 <hr />
 <h1 id="concrete-view-classes">Concrete View Classes</h1>
 <p>The following classes are the concrete generic views.  If you're using generic views this is normally the level you'll be working at unless you need heavily customized behavior.</p>
+<p>The view classes can be imported from <code>rest_framework.generics</code>.</p>
 <h2 id="createapiview">CreateAPIView</h2>
 <p>Used for <strong>create-only</strong> endpoints.</p>
 <p>Provides a <code>post</code> method handler.</p>
diff --git a/api-guide/relations/index.html b/api-guide/relations/index.html
index 85378cc5..ee51a7e3 100644
--- a/api-guide/relations/index.html
+++ b/api-guide/relations/index.html
@@ -664,6 +664,7 @@ class Track(models.Model):
 <ul>
 <li><code>view_name</code> - The view name that should be used as the target of the relationship.  If you're using <a href="http://www.django-rest-framework.org/api-guide/routers#defaultrouter">the standard router classes</a> this will be a string with the format <code>&lt;model_name&gt;-detail</code>.  <strong>required</strong>.</li>
 <li><code>lookup_field</code> - The field on the target that should be used for the lookup.  Should correspond to a URL keyword argument on the referenced view.  Default is <code>'pk'</code>.</li>
+<li><code>lookup_url_kwarg</code> - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as <code>lookup_field</code>.</li>
 <li><code>format</code> - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the <code>format</code> argument.</li>
 </ul>
 <hr />
diff --git a/api-guide/routers/index.html b/api-guide/routers/index.html
index 32022b86..70d136f4 100644
--- a/api-guide/routers/index.html
+++ b/api-guide/routers/index.html
@@ -475,6 +475,32 @@ urlpatterns = router.urls
 </code></pre>
 <p>This means you'll need to explicitly set the <code>base_name</code> argument when registering the viewset, as it could not be automatically determined from the model name.</p>
 <hr />
+<h3 id="using-include-with-routers">Using <code>include</code> with routers</h3>
+<p>The <code>.urls</code> attribute on a router instance is simply a standard list of URL patterns. There are a number of different styles for how you can include these URLs.</p>
+<p>For example, you can append <code>router.urls</code> to a list of existing views…</p>
+<pre><code>router = routers.SimpleRouter()
+router.register(r'users', UserViewSet)
+router.register(r'accounts', AccountViewSet)
+
+urlpatterns = [
+    url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+]
+
+urlpatterns += router.urls
+</code></pre>
+<p>Alternatively you can use Django's <code>include</code> function, like so…</p>
+<pre><code>urlpatterns = [
+    url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+    url(r'^', include(router.urls))
+]
+</code></pre>
+<p>Router URL patterns can also be namespaces.</p>
+<pre><code>urlpatterns = [
+    url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+    url(r'^api/', include(router.urls, namespace='api'))
+]
+</code></pre>
+<p>If using namespacing with hyperlinked serializers you'll also need to ensure that any <code>view_name</code> parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as <code>view_name='api:user-detail'</code> for serializer fields hyperlinked to the user detail view.</p>
 <h3 id="extra-link-and-actions">Extra link and actions</h3>
 <p>Any methods on the viewset decorated with <code>@detail_route</code> or <code>@list_route</code> will also be routed.
 For example, given a method like this on the <code>UserViewSet</code> class:</p>
@@ -492,6 +518,22 @@ class UserViewSet(ModelViewSet):
 <ul>
 <li>URL pattern: <code>^users/{pk}/set_password/$</code>  Name: <code>'user-set-password'</code></li>
 </ul>
+<p>If you do not want to use the default URL generated for your custom action, you can instead use the url_path parameter to customize it.</p>
+<p>For example, if you want to change the URL for our custom action to <code>^users/{pk}/change-password/$</code>, you could write:</p>
+<pre><code>from myapp.permissions import IsAdminOrIsSelf
+from rest_framework.decorators import detail_route
+
+class UserViewSet(ModelViewSet):
+    ...
+
+    @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf], url_path='change-password')
+    def set_password(self, request, pk=None):
+        ...
+</code></pre>
+<p>The above example would now generate the following URL pattern:</p>
+<ul>
+<li>URL pattern: <code>^users/{pk}/change-password/$</code>  Name: <code>'user-change-password'</code></li>
+</ul>
 <p>For more information see the viewset documentation on <a href="../../viewsets.html#marking-extra-actions-for-routing">marking extra actions for routing</a>.</p>
 <h1 id="api-guide">API Guide</h1>
 <h2 id="simplerouter">SimpleRouter</h2>
diff --git a/api-guide/serializers/index.html b/api-guide/serializers/index.html
index 64d6c8b9..4bb06d3b 100644
--- a/api-guide/serializers/index.html
+++ b/api-guide/serializers/index.html
@@ -868,7 +868,7 @@ serializer.errors
         has_support_contract=validated_data['profile']['has_support_contract']
     )
 </code></pre>
-<p>For more details on this approach see the Django documentation on <a href="../../model-managers">model managers</a>, and <a href="../../encapsulation-blogpost">this blogpost on using model and manger classes</a>.</p>
+<p>For more details on this approach see the Django documentation on <a href="../../model-managers">model managers</a>, and <a href="../../encapsulation-blogpost">this blogpost on using model and manager classes</a>.</p>
 <h2 id="dealing-with-multiple-objects">Dealing with multiple objects</h2>
 <p>The <code>Serializer</code> class can also handle serializing or deserializing lists of objects.</p>
 <h4 id="serializing-multiple-objects">Serializing multiple objects</h4>