12 files changed, 131 insertions, 23 deletions
diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 7caeac1e..1a1c68b8 100755
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -265,6 +265,12 @@ This authentication class depends on the optional [django-oauth2-provider][djang
         'provider.oauth2',
     )
 
+Then add `OAuth2Authentication` to your global `DEFAULT_AUTHENTICATION` setting:
+
+    'DEFAULT_AUTHENTICATION_CLASSES': (
+        'rest_framework.authentication.OAuth2Authentication',
+    ),
+
 You must also include the following in your root `urls.py` module:
 
     url(r'^oauth2/', include('provider.oauth2.urls', namespace='oauth2')),
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index 0c48783a..c46d415e 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -82,7 +82,7 @@ Note that the exception handler will only be called for responses generated by r
 
 ## APIException
 
-**Signature:** `APIException(detail=None)`
+**Signature:** `APIException()`
 
 The **base class** for all exceptions raised inside REST framework.
 
diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index 962c49e2..4272c9a7 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -299,9 +299,9 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files.
 
 # Custom fields
 
-If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods.  These two methods are used to convert between the initial datatype, and a primative, serializable datatype.  Primative datatypes may be any of a number, string, date/time/datetime or None.  They may also be any list or dictionary like object that only contains other primative objects.
+If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods.  These two methods are used to convert between the initial datatype, and a primitive, serializable datatype.  Primitive datatypes may be any of a number, string, date/time/datetime or None.  They may also be any list or dictionary like object that only contains other primitive objects.
 
-The `.to_native()` method is called to convert the initial datatype into a primative, serializable datatype.  The `from_native()` method is called to restore a primative datatype into it's initial representation.
+The `.to_native()` method is called to convert the initial datatype into a primitive, serializable datatype.  The `from_native()` method is called to restore a primitive datatype into it's initial representation.
 
 ## Examples
 
diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md
index 784aa585..a0132ffc 100644
--- a/docs/api-guide/filtering.md
+++ b/docs/api-guide/filtering.md
@@ -165,8 +165,8 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
     from rest_framework import generics
 
     class ProductFilter(django_filters.FilterSet):
-        min_price = django_filters.NumberFilter(lookup_type='gte')
-        max_price = django_filters.NumberFilter(lookup_type='lte')
+        min_price = django_filters.NumberFilter(name="price", lookup_type='gte')
+        max_price = django_filters.NumberFilter(name="price", lookup_type='lte')
         class Meta:
             model = Product
             fields = ['category', 'in_stock', 'min_price', 'max_price']
@@ -176,10 +176,49 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
         serializer_class = ProductSerializer
         filter_class = ProductFilter
 
+
 Which will allow you to make requests such as:
 
     http://example.com/api/products?category=clothing&max_price=10.00
 
+You can also span relationships using `django-filter`, let's assume that each
+product has foreign key to `Manufacturer` model, so we create filter that
+filters using `Manufacturer` name. For example:
+
+    import django_filters
+    from myapp.models import Product
+    from myapp.serializers import ProductSerializer
+    from rest_framework import generics
+
+    class ProductFilter(django_filters.FilterSet):
+        class Meta:
+            model = Product
+            fields = ['category', 'in_stock', 'manufacturer__name`]
+
+This enables us to make queries like:
+
+    http://example.com/api/products?manufacturer__name=foo
+
+This is nice, but it shows underlying model structure in REST API, which may
+be undesired, but you can use:
+
+    import django_filters
+    from myapp.models import Product
+    from myapp.serializers import ProductSerializer
+    from rest_framework import generics
+
+    class ProductFilter(django_filters.FilterSet):
+
+        manufacturer = django_filters.CharFilter(name="manufacturer__name")
+
+        class Meta:
+            model = Product
+            fields = ['category', 'in_stock', 'manufacturer`]
+
+And now you can execute:
+
+    http://example.com/api/products?manufacturer=foo
+    
 For more details on using filter sets see the [django-filter documentation][django-filter-docs].
 
 ---
diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md
index dc0076df..b9242724 100755
--- a/docs/api-guide/generic-views.md
+++ b/docs/api-guide/generic-views.md
@@ -65,7 +65,8 @@ The following attributes control the basic view behavior.
 
 * `queryset` - The queryset that should be used for returning objects from this view.  Typically, you must either set this attribute, or override the `get_queryset()` method.
 * `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output.  Typically, you must either set this attribute, or override the `get_serializer_class()` method.
-* `lookup_field` - The field that should be used to lookup individual model instances.  Defaults to `'pk'`.  The URL conf should include a keyword argument corresponding to this value.  More complex lookup styles can be supported by overriding the `get_object()` method.  Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes use lookup fields that correctly correspond with the URL conf.
+* `lookup_field` - The model field that should be used to for performing object lookup of individual model instances.  Defaults to `'pk'`.  Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes set the lookup fields if you need to use a custom value.
+* `lookup_url_kwarg` - The URL keyword argument that should be used for object lookup.  The URL conf should include a keyword argument corresponding to this value.  If unset this defaults to using the same value as `lookup_field`.
 
 **Shortcuts**:
 
@@ -120,11 +121,27 @@ For example:
 
 Note that if your API doesn't include any object level permissions, you may optionally exclude the ``self.check_object_permissions, and simply return the object from the `get_object_or_404` lookup.
 
+#### `get_filter_backends(self)`
+
+Returns the classes that should be used to filter the queryset. Defaults to returning the `filter_backends` attribute.
+
+May be override to provide more complex behavior with filters, as using different (or even exlusive) lists of filter_backends depending on different criteria.
+
+For example:
+
+    def get_filter_backends(self):
+        if "geo_route" in self.request.QUERY_PARAMS:
+            return (GeoRouteFilter, CategoryFilter)
+        elif "geo_point" in self.request.QUERY_PARAMS:
+            return (GeoPointFilter, CategoryFilter)
+
+        return (CategoryFilter,)
+
 #### `get_serializer_class(self)`
 
 Returns the class that should be used for the serializer.  Defaults to returning the `serializer_class` attribute, or dynamically generating a serializer class if the `model` shortcut is being used.
 
-May be override to provide dynamic behavior such as using different serializers for read and write operations, or providing different serializers to different types of uesr.
+May be override to provide dynamic behavior such as using different serializers for read and write operations, or providing different serializers to different types of users.
 
 For example:
 
@@ -327,7 +344,7 @@ You can then simply apply this mixin to a view or viewset anytime you need to ap
         serializer_class = UserSerializer
         lookup_fields = ('account', 'username')
 
-Using custom mixins is a good option if you have custom behavior that needs to be used 
+Using custom mixins is a good option if you have custom behavior that needs to be used
 
 ## Creating custom base classes
 
@@ -336,7 +353,7 @@ If you are using a mixin across multiple views, you can take this a step further
     class BaseRetrieveView(MultipleFieldLookupMixin,
                            generics.RetrieveAPIView):
         pass
-    
+
     class BaseRetrieveUpdateDestroyView(MultipleFieldLookupMixin,
                                         generics.RetrieveUpdateDestroyAPIView):
         pass
diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md
index 657377d9..1f286ef1 100644
--- a/docs/api-guide/renderers.md
+++ b/docs/api-guide/renderers.md
@@ -409,6 +409,10 @@ The following third party packages are also available.
 
 Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications.  [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework.
 
+## UltraJSON
+
+[UltraJSON][ultrajson] is a blazing-fast C JSON encoder which can give 2-10x performance increases on typical workloads. [Jacob Haslehurst][hzy] maintains the [drf-ujson-renderer][drf-ujson-renderer] package which implements JSON rendering using the UJSON package.
+
 [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/#the-rendering-process
 [conneg]: content-negotiation.md
 [browser-accept-headers]: http://www.gethifi.com/blog/browser-rest-http-accept-headers
@@ -426,3 +430,6 @@ Comma-separated values are a plain-text tabular data format, that can be easily
 [mjumbewu]: https://github.com/mjumbewu
 [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack
 [djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv
+[ultrajson]: https://github.com/esnme/ultrajson
+[hzy]: https://github.com/hzy
+[drf-ujson-renderer]: https://github.com/gizmag/drf-ujson-renderer
diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index 35c1f766..4a8a9168 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -205,10 +205,10 @@ You can use any of REST framework's test case classes as you would for the regul
             Ensure we can create a new account object.
             """
             url = reverse('account-list')
-            expected = {'name': 'DabApps'}
+            data = {'name': 'DabApps'}
             response = self.client.post(url, data, format='json')
             self.assertEqual(response.status_code, status.HTTP_201_CREATED)
-            self.assertEqual(response.data, expected)
+            self.assertEqual(response.data, data)
 
 ---
 
diff --git a/docs/template.html b/docs/template.html
index a20c8111..749d0afe 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -167,7 +167,32 @@
             <div id="table-of-contents">
               <ul class="nav nav-list side-nav well sidebar-nav-fixed">
                 {{ toc }}
+              <div>
+              <hr>
+
+<p><strong>The team behind REST framework are launching a new API service.</strong></p>
+
+<p>If you want to be first in line when we start issuing invitations, please sign up here:</p>
+
+<!-- Begin MailChimp Signup Form -->
+<link href="//cdn-images.mailchimp.com/embedcode/slim-081711.css" rel="stylesheet" type="text/css">
+<style type="text/css">
+    #mc_embed_signup{background:#fff; clear:left; font:14px Helvetica,Arial,sans-serif; }
+    /* Add your own MailChimp form style overrides in your site stylesheet or in this style block.
+       We recommend moving this block and the preceding CSS link to the HEAD of your HTML file. */
+</style>
+<div id="mc_embed_signup" style="background: rgb(245, 245, 245)">
+<form action="http://dabapps.us1.list-manage1.com/subscribe/post?u=cf73a9994eb5b8d8d461b5dfb&amp;id=cb6af8e8bd" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate>
+<!--     <label for="mce-EMAIL">Keep me posted!</label>
+ -->    <input style="width: 90%" type="email" value="" name="EMAIL" class="email" id="mce-EMAIL" placeholder="email address" required>
+    <div class="clear"><input class="btn btn-success" type="submit" value="Yes, keep me posted!" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
+</form>
+</div>
+</style></div>
               </ul>
+
+
+<!--End mc_embed_signup-->
             </div>
           </div>
 
diff --git a/docs/topics/credits.md b/docs/topics/credits.md
index 586bb0f0..9751850b 100644
--- a/docs/topics/credits.md
+++ b/docs/topics/credits.md
@@ -171,6 +171,13 @@ The following people have helped make REST framework great.
 * Tai Lee - [mrmachine]
 * Markus Kaiserswerth - [mkai]
 * Henry Clifford - [hcliff]
+* Thomas Badaud - [badale]
+* Colin Huang - [tamakisquare]
+* Ross McFarland - [ross]
+* Jacek Bzdak - [jbzdak]
+* Alexander Lukanin - [alexanderlukanin13]
+* Yamila Moreno - [yamila-moreno]
+* Rob Hudson - [robhudson]
 
 Many thanks to everyone who's contributed to the project.
 
@@ -378,3 +385,10 @@ You can also contact [@_tomchristie][twitter] directly on twitter.
 [mrmachine]: https://github.com/mrmachine
 [mkai]: https://github.com/mkai
 [hcliff]: https://github.com/hcliff
+[badale]: https://github.com/badale
+[tamakisquare]: https://github.com/tamakisquare
+[ross]: https://github.com/ross
+[jbzdak]: https://github.com/jbzdak
+[alexanderlukanin13]: https://github.com/alexanderlukanin13
+[yamila-moreno]: https://github.com/yamila-moreno
+[robhudson]: https://github.com/robhudson
diff --git a/docs/tutorial/2-requests-and-responses.md b/docs/tutorial/2-requests-and-responses.md
index 6ff97f37..7fa4f3e4 100644
--- a/docs/tutorial/2-requests-and-responses.md
+++ b/docs/tutorial/2-requests-and-responses.md
@@ -35,7 +35,7 @@ The wrappers also provide behaviour such as returning `405 Method Not Allowed` r
 
 Okay, let's go ahead and start using these new components to write a few views. 
 
-We don't need our `JSONResponse` class anymore, so go ahead and delete that.  Once that's done we can start refactoring our views slightly.
+We don't need our `JSONResponse` class in `views.py` anymore, so go ahead and delete that.  Once that's done we can start refactoring our views slightly.
 
     from rest_framework import status
     from rest_framework.decorators import api_view
@@ -64,7 +64,7 @@ We don't need our `JSONResponse` class anymore, so go ahead and delete that.  On
 
 Our instance view is an improvement over the previous example.  It's a little more concise, and the code now feels very similar to if we were working with the Forms API.  We're also using named status codes, which makes the response meanings more obvious.
 
-Here is the view for an individual snippet.
+Here is the view for an individual snippet, in the `views.py` module.
 
     @api_view(['GET', 'PUT', 'DELETE'])
     def snippet_detail(request, pk):
diff --git a/docs/tutorial/3-class-based-views.md b/docs/tutorial/3-class-based-views.md
index 9fc424fe..b37bc31b 100644
--- a/docs/tutorial/3-class-based-views.md
+++ b/docs/tutorial/3-class-based-views.md
@@ -4,7 +4,7 @@ We can also write our API views using class based views, rather than function ba
 
 ## Rewriting our API using class based views
 
-We'll start by rewriting the root view as a class based view.  All this involves is a little bit of refactoring.
+We'll start by rewriting the root view as a class based view.  All this involves is a little bit of refactoring of `views.py`.
 
     from snippets.models import Snippet
     from snippets.serializers import SnippetSerializer
@@ -30,7 +30,7 @@ We'll start by rewriting the root view as a class based view.  All this involves
                 return Response(serializer.data, status=status.HTTP_201_CREATED)
             return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
 
-So far, so good.  It looks pretty similar to the previous case, but we've got better separation between the different HTTP methods.  We'll also need to update the instance view. 
+So far, so good.  It looks pretty similar to the previous case, but we've got better separation between the different HTTP methods.  We'll also need to update the instance view in `views.py`. 
 
     class SnippetDetail(APIView):
         """
@@ -62,7 +62,7 @@ So far, so good.  It looks pretty similar to the previous case, but we've got be
 
 That's looking good.  Again, it's still pretty similar to the function based view right now.
 
-We'll also need to refactor our URLconf slightly now we're using class based views.
+We'll also need to refactor our `urls.py` slightly now we're using class based views.
 
     from django.conf.urls import patterns, url
     from rest_framework.urlpatterns import format_suffix_patterns
@@ -83,7 +83,7 @@ One of the big wins of using class based views is that it allows us to easily co
 
 The create/retrieve/update/delete operations that we've been using so far are going to be pretty similar for any model-backed API views we create.  Those bits of common behaviour are implemented in REST framework's mixin classes.
 
-Let's take a look at how we can compose our views by using the mixin classes.
+Let's take a look at how we can compose the views by using the mixin classes.  Here's our `views.py` module again.
 
     from snippets.models import Snippet
     from snippets.serializers import SnippetSerializer
@@ -126,7 +126,7 @@ Pretty similar.  Again we're using the `GenericAPIView` class to provide the cor
 
 ## Using generic class based views
 
-Using the mixin classes we've rewritten the views to use slightly less code than before, but we can go one step further.  REST framework provides a set of already mixed-in generic views that we can use.
+Using the mixin classes we've rewritten the views to use slightly less code than before, but we can go one step further.  REST framework provides a set of already mixed-in generic views that we can use to trim down our `views.py` module even more.
 
     from snippets.models import Snippet
     from snippets.serializers import SnippetSerializer
diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md
index 510aa243..ecf92a7b 100644
--- a/docs/tutorial/4-authentication-and-permissions.md
+++ b/docs/tutorial/4-authentication-and-permissions.md
@@ -12,7 +12,7 @@ Currently our API doesn't have any restrictions on who can edit or delete code s
 We're going to make a couple of changes to our `Snippet` model class.
 First, let's add a couple of fields.  One of those fields will be used to represent the user who created the code snippet.  The other field will be used to store the highlighted HTML representation of the code.
 
-Add the following two fields to the model.
+Add the following two fields to the `Snippet` model in `models.py`.
 
     owner = models.ForeignKey('auth.User', related_name='snippets')
     highlighted = models.TextField()
@@ -52,7 +52,7 @@ You might also want to create a few different users, to use for testing the API.
 
 ## Adding endpoints for our User models
 
-Now that we've got some users to work with, we'd better add representations of those users to our API.  Creating a new serializer is easy:
+Now that we've got some users to work with, we'd better add representations of those users to our API.  Creating a new serializer is easy. In `serializers.py` add:
 
     from django.contrib.auth.models import User
 
@@ -65,7 +65,7 @@ Now that we've got some users to work with, we'd better add representations of t
 
 Because `'snippets'` is a *reverse* relationship on the User model, it will not be included by default when using the `ModelSerializer` class, so we needed to add an explicit field for it.
 
-We'll also add a couple of views.  We'd like to just use read-only views for the user representations, so we'll use the `ListAPIView` and `RetrieveAPIView` generic class based views.
+We'll also add a couple of views to `views.py`.  We'd like to just use read-only views for the user representations, so we'll use the `ListAPIView` and `RetrieveAPIView` generic class based views.
 
     class UserList(generics.ListAPIView):
         queryset = User.objects.all()
@@ -80,7 +80,7 @@ Make sure to also import the `UserSerializer` class
 
 	from snippets.serializers import UserSerializer
 
-Finally we need to add those views into the API, by referencing them from the URL conf.
+Finally we need to add those views into the API, by referencing them from the URL conf. Add the following to the patterns in `urls.py`.
 
     url(r'^users/$', views.UserList.as_view()),
     url(r'^users/(?P<pk>[0-9]+)/$', views.UserDetail.as_view()),
@@ -98,7 +98,7 @@ On **both** the `SnippetList` and `SnippetDetail` view classes, add the followin
 
 ## Updating our serializer
 
-Now that snippets are associated with the user that created them, let's update our `SnippetSerializer` to reflect that.  Add the following field to the serializer definition:
+Now that snippets are associated with the user that created them, let's update our `SnippetSerializer` to reflect that.  Add the following field to the serializer definition in `serializers.py`:
 
     owner = serializers.Field(source='owner.username')